> Documentation index: https://docs.scrapier.io/llms.txt
> Auth: header `X-API-Key: <key>` · Base: https://api.scrapier.io/api/v2 · Synchronous; paginate with `cursor` ← `data.next_cursor`.

# Amazon Products

Search Amazon by keyword or URL and get product listings, or send a product URL to get that single product.

`GET|POST https://api.scrapier.io/api/v2/amazon-product/` · 1 credit per successful call · Cursor-paginated

## Overview

This endpoint works in two modes. Send a keyword in `query` (or an Amazon search or category URL in `url`) and you get a page of product listings that you can paginate with `cursor`.

Send a product /dp/ URL in `url` instead and you get a single result with `next_cursor` set to `null`. When you send both, `url` takes precedence over `query`. The `mode` field in the response tells you which mode ran.

Pick the marketplace and delivery location with `location_name` (or override the domain with `se_domain` and the postal code with `zip_code`), and narrow results with `price_min`, `price_max`, `sort_by` and `department`.

## Use cases

- Search Amazon from a keyword without building the search URL yourself.
- Re-crawl an existing Amazon search or category page you already have the URL for.
- Look up one product by its URL with the same endpoint you use for search.

## Request

```bash
curl -G "https://api.scrapier.io/api/v2/amazon-product/" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "query=keyboard" \
  --max-time 210
```

```python
import requests

resp = requests.get(
    "https://api.scrapier.io/api/v2/amazon-product/",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"query": "keyboard"},
    timeout=210,
)
body = resp.json()
if not resp.ok:
    raise RuntimeError(body.get("error") or body.get("detail"))

print(body["data"]["item_types"])
```

POST with a JSON body works too (same parameters; the body is merged over the query string).

## Parameters

> **Note:** Send one of `query` or `url`.

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `X-API-Key` (header) | string | yes | — | Your API key. |
| `query` | string | no | `keyboard` | Search keyword. Builds the marketplace search URL (see location_name / se_domain) when url is omitted. Required first call unless url given. Aliases: queries, keyword, q. |
| `url` | string | no | — | Amazon search/category URL or product /dp/ URL. Takes precedence over query. Product URLs return a single result with next_cursor=null; search URLs paginate. Aliases: urls. |
| `cursor` | string | no | — | Pagination cursor returned in the previous response's `next_cursor`. Pass it back unchanged to fetch the next page. When `next_cursor` is null, you have reached the last page. |
| `location_name` | string | no | `United States` | Marketplace + delivery location. Sets the Amazon domain, currency and delivery ZIP (prices/delivery dates as a shopper there sees them). Aliases: location, location_code (e.g. 2840), country (ISO2). One of: `United States`, `Australia`, `Belgium`, `Brazil`, `Canada`, `France`, `Germany`, `India`, `Italy`, `Japan`, `Mexico`, `Netherlands`, `Poland`, `Saudi Arabia`, `Singapore`, `Spain`, `Sweden`, `United Arab Emirates`, `Turkiye`, `Egypt`, `United Kingdom`. |
| `language_name` | string | no | — | Storefront language, as a name ("English (United States)") or code (en_US). Default: the marketplace language. Aliases: language, language_code. One of: `English (United States)`, `Arabic (Saudi Arabia)`, `Arabic (U.A.E.)`, `Chinese (Simplified)`, `Chinese (Traditional)`, `Czech (Czech Republic)`, `Dutch (Netherlands)`, `English (Australia)`, `English (Canada)`, `English (India)`, `English (U.A.E.)`, `English (United Kingdom)`, `French (Canada)`, `French (France)`, `German (Germany)`, `Hebrew (Israel)`, `Hindi (India)`, `Italian (Italy)`, `Japanese (Japan)`, `Korean (Korea)`, `Polish (Poland)`, `Portuguese (Brazil)`, `Spanish (Mexico)`, `Spanish (Spain)`, `Spanish (United States)`, `Swedish (Sweden)`, `Turkish (Turkey)`. |
| `se_domain` | string | no | — | Amazon domain override (amazon.com, amazon.co.uk, amazon.de, …). Default: chosen from location_name. |
| `zip_code` | string | no | — | Delivery postal code override (default: the marketplace capital, e.g. 10001 for the US). Aliases: postal_code, zip. |
| `set_delivery_location` | boolean | no | `true` | Pin the session delivery location to zip_code before scraping (2 extra requests per session). false = whatever location Amazon infers from the proxy IP (off-country IPs may get no prices). |
| `price_min` | integer | no | — | Minimum product price (marketplace currency). |
| `price_max` | integer | no | — | Maximum product price (marketplace currency). |
| `sort_by` | string | no | — | Result sorting. Default: Amazon's "Featured" order. One of: `relevance`, `featured`, `price_low_to_high`, `price_high_to_low`, `avg_customer_review`, `newest_arrival`, `best_sellers`. |
| `department` | string | no | — | Amazon department, e.g. "Electronics", "Books", "Home & Kitchen" (or a raw search alias like "electronics"). |
| `search_param` | string | no | — | Extra Amazon search URL params, e.g. "&rh=p_72:1248882011". Ignored when price_min, price_max or sort_by is set. |
| `tag` | string | no | — | Your own identifier (max 255 chars), echoed on every result. |
| `depth` | integer | no | `100` | Max products across all pages, organic + sponsored (max 700). Pagination stops once reached. Alias: max_items. Locked in cursor. |
| `max_crawl_pages` | integer | no | `7` | Max search-result pages to walk; next_cursor is null after this page. Alias: max_pages. Locked in cursor. |
| `use_proxy` | boolean | no | `true` | Route the request through Scrapier's residential proxy pool. Default: `true`. Leave as is unless support tells you otherwise. |
| `raw_data` | boolean | no | `false` | When true, the response carries the full raw upstream payload(s) the scraper received (GraphQL / JSON API bodies, HTML, embedded JSON-LD -- exactly as the platform returned them) under `raw_responses`, in place of the formatted items. When false (default) you get the formatted output. Pagination (`cursor` / `next_cursor`) works the same in both modes. |

## Response

HTTP 200. Results are in `data.item_types`. Sample from the live catalog, arrays trimmed to 3 items.

```json
{
  "success": true,
  "data": {
    "url": "https://www.amazon.com/s?k=iphone&language=en_US&page=1",
    "mode": "search",
    "page": 1,
    "page_size": 20,
    "keyword": "iphone",
    "type": "organic",
    "se_domain": "amazon.com",
    "location_code": 2840,
    "location_name": "United States",
    "language_code": "en_US",
    "check_url": "https://www.amazon.com/s?k=iphone&language=en_US&page=1",
    "datetime": "2026-10-01 07:15:36 +00:00",
    "spell": null,
    "item_types": [
      "amazon_serp",
      "amazon_paid",
      "related_searches"
    ],
    "se_results_count": 268,
    "total_pages": 17,
    "categories": null,
    "items_count": 16,
    "tag": null,
    "related_searches": {
      "type": "related_searches",
      "rank_group": 1,
      "rank_absolute": 18,
      "xpath": "/html[1]/body[1]/div[1]/div[1]/div[1]/div[1]/div[1]/span[1]/div[1]/div[24]",
      "items": [
        {
          "type": "related_searches_element",
          "title": "iphone 13",
          "url": "https://www.amazon.com/s?k=iphone+13",
          "image_alt": null,
          "image_url": null
        }
      ]
    },
    "editorial_recommendations": null,
    "top_rated_from_our_brands": null,
    "products": [
      {
        "type": "amazon_serp",
        "rank_group": 1,
        "rank_absolute": 1,
        "position": "left",
        "xpath": "/html[1]/body[1]/div[1]/div[1]/div[1]/div[1]/div[1]/span[1]/div[1]/div[4]",
        "domain": "www.amazon.com",
        "title": "iPhone 14, 128GB, Midnight - Unlocked (Renewed)",
        "url": "https://www.amazon.com/Apple-iPhone-14-128GB-Midnight/dp/B0BN72FYFG/ref=sr_1_1",
        "image_url": "https://m.media-amazon.com/images/I/61WUSYIQdKL._AC_UY218_.jpg",
        "bought_past_month": 7000,
        "price_from": 299.95,
        "price_to": null,
        "currency": "USD",
        "special_offers": null,
        "data_asin": "B0BN72FYFG",
        "rating": {
          "type": "rating_element",
          "position": "left",
          "rating_type": "Max5",
          "value": 4,
          "votes_count": 13868,
          "rating_max": 5
        },
        "is_amazon_choice": false,
        "is_best_seller": true,
        "delivery_info": {
          "delivery_message": "FREE delivery Tomorrow, Oct 2",
          "delivery_price": null
        },
        "labels": null,
        "is_sponsored": false,
        "bought_past_month_text": "7K+ bought in past month",
        "best_seller_category": "in Renewed Smartphones",
        "badges": [
          "Best Seller"
        ],
        "unit_price": null,
        "more_buying_choices": {
          "text": "More Buying Choices $273.00 (44+ used & new offers)",
          "price": 273,
          "offers_text": "44+ used & new offers"
        },
        "product_details": [
          {
            "key": "Memory",
            "value": "128 GB"
          },
          {
            "key": "Color",
            "value": "Midnight"
          }
        ],
        "asin": "B0BN72FYFG",
        "price": {
          "value": 299.95,
          "currency": "$"
        },
        "list_price": null,
        "brand": "Amazon Renewed",
        "stars": 4,
        "reviews_count": 13868,
        "in_stock": true,
        "thumbnail_image": "https://m.media-amazon.com/images/I/61WUSYIQdKL._AC_UY218_.jpg",
        "category_page_data": {
          "page_number": 1,
          "product_position": 1,
          "is_sponsored": false
        },
        "loaded_country_code": "US",
        "details_scraped": false,
        "input_url": "https://www.amazon.com/s?k=iphone&language=en_US&page=1"
      }
    ],
    "next_cursor": "eyJjIjp7Li4ufSwiaCI6ImFiYzEyMyIsIm4iOjE2LCJwIjoyLCJ1IjoiaHR0cHM6Ly93d3cuYW1hem9uLmNvbS9zP2s9aXBob25lIn0"
  }
}
```

## Response fields

| Field | Type | Example | Description |
|---|---|---|---|
| `url` | string | `https://www.amazon.com/s?k=iphone&language=en…` |  |
| `mode` | string | `search` | Which mode ran, for example search. |
| `page` | integer | `1` |  |
| `page_size` | integer | `20` |  |
| `keyword` | string | `iphone` |  |
| `type` | string | `organic` |  |
| `se_domain` | string | `amazon.com` |  |
| `location_code` | integer | `2840` |  |
| `location_name` | string | `United States` |  |
| `language_code` | string | `en_US` |  |
| `check_url` | string | `https://www.amazon.com/s?k=iphone&language=en…` |  |
| `datetime` | string | `2026-10-01 07:15:36 +00:00` |  |
| `spell` | null | `null` |  |
| `item_types` | array | `[3 items]` | The results. |
| `se_results_count` | integer | `268` |  |
| `total_pages` | integer | `17` |  |
| `categories` | null | `null` |  |
| `items_count` | integer | `16` |  |
| `tag` | null | `null` |  |
| `related_searches` | object | `{…}` |  |
| `editorial_recommendations` | null | `null` |  |
| `top_rated_from_our_brands` | null | `null` |  |
| `products` | array | `[1 item]` |  |
| `next_cursor` | string | `eyJjIjp7Li4ufSwiaCI6ImFiYzEyMyIsIm4iOjE2LCJwI…` | Pass back as `cursor` for the next page. `null` on the last page. |

## Pagination

Pass `data.next_cursor` back as `cursor` until it is `null`. Required inputs are ignored once a cursor is sent. Each page is one billed call.

```python
import requests

URL = "https://api.scrapier.io/api/v2/amazon-product/"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}
params = {"query": "keyboard"}
items = []

for _ in range(10):  # each page is one billed call
    resp = requests.get(URL, headers=HEADERS, params=params, timeout=210)
    resp.raise_for_status()
    data = resp.json()["data"]
    items.extend(data.get("item_types") or [])
    if not data.get("next_cursor"):  # None = last page
        break
    params = {"cursor": data["next_cursor"]}
```

## Errors

Failed calls are free. Branch on HTTP status; the message is in `error` (or `detail`). See https://docs.scrapier.io/errors.md

- **400** Bad input. The exact message varies by endpoint. `{"success":false,"error":"…"}`
- **402** Balance below the endpoint's price. `{"error":"Insufficient credits. Buy more to scrape more.","balance":1,"required":2}`
- **403** Invalid or unknown API key. `{"detail":"Authentication service unavailable or invalid API key."}`
- **429** Throttled — wait for Retry-After. `{"detail":"Request was throttled. Expected available in N seconds."}`
- **404** unknown slug · **503** busy (retry after `Retry-After`) · **5xx** upstream failure or timeout (retry with backoff).

## Notes

- Send one of `query` or `url` on the first call. If both are present, `url` wins.
- A product URL returns a single result and no further pages; search and category URLs paginate.
- `price` is an object with `value` and `currency` in this endpoint's sample.
- `depth` caps the products collected across all pages (default 100, max 700) and `max_crawl_pages` caps the pages walked (default 7). Both are locked into the cursor.
- `set_delivery_location` is on by default and costs 2 extra requests per session; turn it off to use whatever location Amazon infers from the proxy IP, which can return no prices.
- Locked into the cursor: `depth`, `max_crawl_pages`. Set them on the first call; later pages reuse them.

## Related

- [Amazon Search](https://docs.scrapier.io/api-reference/amazon/amazon-search.md): Search Amazon by keyword and get product results with price, rating and position, with marketplace and sort order options.
- [Amazon Product Reviews](https://docs.scrapier.io/api-reference/amazon/amazon-review.md): Get the reviews Amazon shows for a product from its ASIN or product URL, with rating, text, author and date.
- [Amazon Sellers](https://docs.scrapier.io/api-reference/amazon/amazon-seller-scraper.md): Find who sells the products for a search term, search URL, product URL or ASIN, with seller business name, phone, address and offers.
