# Amazon (/docs/amazon)



Amazon [#amazon]

Search Amazon and pull real product, review, and seller data — plus influencer storefronts — behind the
unified SocialCrawl schema. A row from Amazon has the same leaf names as a row from Walmart, Target, eBay
or Google Shopping, so a price-comparison integration needs one mapping rather than one per retailer.

Base URL: `/v1/amazon/...`

Repeated `product-search` calls may use the 2-minute endpoint cache, `product` and `sellers` the 10-minute cache, and `reviews` the 5-minute cache. Cache hits cost 0 credits; send `Cache-Control: no-cache` to force a billed refresh.

<Callout>
  On the 

  **US**

   marketplace most 

  `/v1/amazon/reviews`

   calls return a refunded 

  `404`

   rather than review rows. Pass a 

  `country`

   such as 

  `CA`

   or 

  `GB`

   when you actually need review text — the empty US call costs you nothing, but it also tells you nothing.
</Callout>

Everything is keyed on the **ASIN**, the 10-character product identifier in any Amazon product
URL. `product-search` is how you turn a keyword into one.

Getting started [#getting-started]

Every endpoint is a `GET` with query parameters and an `x-api-key` header.

```bash
# 1. Keyword to ASINs (1 credit)
curl "https://www.socialcrawl.dev/v1/amazon/product-search?query=airpods%20pro" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 2. Full detail for one ASIN (5 credits)
curl "https://www.socialcrawl.dev/v1/amazon/product?asin=B0FQFB8FMG" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 3. Who else is selling it, and at what price (1 credit)
curl "https://www.socialcrawl.dev/v1/amazon/sellers?asin=B0FQFB8FMG" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Search [#search]

`product-search` returns title, price, rating, image and ASIN per result, page-paginated. Leave
`depth` unset for the fast default page size — that is the right choice when all you want is
keyword-to-ASIN resolution.

`depth` (max 700) exists for the opposite case: when you would rather make one large request
than paginate. It selects a different, slower search backend whose latency grows with the depth
you ask for, at the same flat credit cost. A timeout on that path is auto-refunded.

Product, sellers and reviews [#product-sellers-and-reviews]

`product` returns one ASIN in full: title, brand, description, price, rating, image gallery,
specifications and the variant ASINs. `sellers` returns every offer on that ASIN — seller name,
price, rating and condition (new, used, refurbished) — including which one holds the buy box,
which is the endpoint you want for competitive pricing rather than catalogue pricing.

`/v1/amazon/reviews` returns the customer reviews shown on the product page, roughly eight per
ASIN, each with full text, star rating, reviewer, verified-purchase flag and photos.

`/v1/amazon/shop` is the odd one out: it takes a storefront `url` rather than an ASIN and
returns the products an influencer or seller has put on their own shop page. Use it when the
curation is the point.

Endpoints [#endpoints]

<PlatformEndpoints platform="amazon" />

Read this before you build [#read-this-before-you-build]

**US reviews mostly come back empty, and that is not a bug in your code.** On the US
marketplace, most `reviews` requests return a refunded `404` rather than review rows. Pass a
`country` such as `CA` or `GB` when you actually need review text. The call costs you nothing
when it returns nothing.

**Reviews are family-wide.** Amazon shows reviews across a product's whole variant family, so a
returned review can originate from a sibling ASIN. `review.entity_id` is always the ASIN you
asked for, so use that rather than assuming provenance.

**Non-US marketplaces are best effort.** `country` accepts `US`, `GB`, `CA`, `DE`, `FR`, `IT`,
`ES`, `JP`, `IN`, `MX`, `BR`, `AU` and `NL`, and defaults to `US`. The upstream is slower for
the non-US marketplaces, especially in the EU, and occasionally times out. Those calls are
refunded, and US remains the most reliable marketplace.

**`product` and `reviews` share one upstream call.** Fetch the product first and its reviews
come warm from cache, or the other way round — the windows are listed at the top of this page.

Notes [#notes]

* All endpoints use `GET` with query parameters
* Authentication via the `x-api-key` header
* Responses follow the unified SocialCrawl schema
* `product-search`, `sellers` and `shop` are 1 credit; `product` and `reviews` are 5
* The product, review and seller endpoints are powered by DataForSEO and return the canonical
  `Product` / `Review` / `Seller` objects shared with the other commerce platforms