# Amazon (/docs/amazon) Amazon keyword search, product detail by ASIN, customer reviews, competing seller offers, and influencer storefronts Amazon product, review, and seller data behind the unified SocialCrawl schema. An Amazon row carries the same leaf names as a Walmart, Target, eBay or Google Shopping row, so a price-comparison integration needs one mapping rather than one per retailer. Base URL: `/v1/amazon/...` 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. `country` defaults to `US`, which is the most reliable marketplace. The non-US marketplaces, the EU ones especially, are best effort: the upstream is slower there and occasionally times out. Those calls are refunded. ## Quickstart ### Resolve a keyword to an ASIN `product-search` is the way in when all you hold is a search term. Every row carries the ASIN the other endpoints need. ```bash title="cURL" curl "https://www.socialcrawl.dev/v1/amazon/product-search?query=airpods%20pro" \ -H "x-api-key: YOUR_API_KEY" ``` ### Read the product, then who else sells it Full catalogue detail for one ASIN, then every competing offer on it. ```bash title="cURL" curl "https://www.socialcrawl.dev/v1/amazon/product?asin=B0FQFB8FMG" \ -H "x-api-key: YOUR_API_KEY" curl "https://www.socialcrawl.dev/v1/amazon/sellers?asin=B0FQFB8FMG" \ -H "x-api-key: YOUR_API_KEY" ``` ## Search | Endpoint | Credits | What it returns | Key parameters | | ------------------------------- | ------- | --------------------------------------------------------------------- | ---------------------------------------------- | | `GET /v1/amazon/product-search` | 1 | Organic results with title, price, list price, rating, image and ASIN | `query` (required), `country`, `depth`, `page` | Leave `depth` unset for the fast default page size. That is the right choice when all you want is keyword-to-ASIN resolution. `depth` (default 20, 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, and a timeout on that path is auto-refunded. ## Products and sellers | Endpoint | Credits | What it returns | Key parameters | | ------------------------ | ------- | ----------------------------------------------------------------------------------------------- | ---------------------------- | | `GET /v1/amazon/product` | 5 | Title, brand, description, price, rating, image gallery, specifications, variant ASINs | `asin` (required), `country` | | `GET /v1/amazon/sellers` | 1 | Every offer on one ASIN: seller name, price, rating, condition, and which one holds the buy box | `asin` (required), `country` | | `GET /v1/amazon/shop` | 1 | The products an influencer or seller lists on their own storefront page | `url` (required) | `sellers` is the competitive-pricing endpoint, `product` the catalogue one. `shop` is the odd one out: it takes a storefront `url` rather than an ASIN, so reach for it when the curation is the point. ## Reviews | Endpoint | Credits | What it returns | Key parameters | | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------- | ---------------------------- | | `GET /v1/amazon/reviews` | 5 | Top reviews with full text, star rating, reviewer, verified-purchase flag, helpful votes, date and photos | `asin` (required), `country`, `label`, `judgments` | ## All endpoints ## Platform notes **Reviews are Amazon's top reviews, not the whole archive.** Each call returns the product's most helpful reviews, usually 10, with the publish date and the reviewer's country. There is no page or cursor parameter. A product with no reviews, or an ASIN that does not exist, returns a refunded empty list or a refunded `404`. **Reviews work on every marketplace.** `country=US` is the default and returns review rows, and so do the other twelve marketplaces. The publish date and reviewer country are read from each store's own wording, so a German or Japanese review carries them too. Mexico (`MX`) is the least reliable and sometimes answers a refunded `404` for a listed product; retry it. **Reviews are family-wide.** Amazon pools 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 read provenance off that rather than assuming it. **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 outside the US, especially in the EU, and occasionally times out. Those calls are refunded. US is the most reliable marketplace for search, product and seller data. **Search returns organic results only.** Sponsored placements and related searches are excluded, so every row is a real ranked result rather than an ad. **Cache hits are free.** `product-search` caches for 2 minutes, `product` and `sellers` for 10, and `reviews` for 5. A hit costs 0 credits. Send `Cache-Control: no-cache` when you need a billed refresh. See [Caching](/docs/caching.md). ## Labels `/v1/amazon/reviews` labels each review by default, at no extra credit: `sentiment` (read from the words, never the stars, with `rating_mismatch` when the two clearly disagree) and `issue` (the main problem the review reports) on `computed.labels`. Send `judgments=off` for the page without them. See [Labels](/docs/labels.md) for the field shapes and the labels you can add with `label=`, such as `label=reports&reports=the battery drains quickly`. ## Next steps - [Pagination](/docs/pagination.md): The universal cursor, and how to walk a search to the end. - [Credits](/docs/credits.md): What each tier costs, and which failures are refunded. - [API reference](/docs/api-reference.md): Every Amazon parameter and response field. - [Walmart](/docs/walmart.md): The same product, review and seller shapes for walmart.com. - [Google Shopping](/docs/google_shopping.md): The cross-retailer view: every store selling one product.