Getting started

Amazon Data API query parameters

Every endpoint takes plain query parameters. A handful are shared across the whole API — learn these four and the rest is per-endpoint detail.

Shared across every endpoint

ParameterTypeDefaultNotes
marketplace string US Two-letter marketplace code (US, UK, DE, FR, IT, ES, CA, JP, IN, AU, …).
zip string — Delivery postcode. Without one, many listings report “cannot be shipped to your location” and come back with no price or images. Always send it for price-accurate data.
page integer 1 1-based page number.
limit integer 0 Search only. Auto-paginate until N items are collected. 0 returns a single page. Maximum 200.

Why zip matters more than you expect

Amazon resolves price, availability and delivery promise against a delivery address. With no postcode, a large share of listings report “cannot be shipped to your location” and return with price: null and no images. It is not an error — it is what Amazon genuinely serves to an unlocated visitor.

Without zip
{
  "asin": "B07CMS5Q6P",
  "title": "Logitech G305 …",
  "price": null,
  "availability": "Cannot be shipped to your location",
  "images": []
}
With zip=10001
{
  "asin": "B07CMS5Q6P",
  "title": "Logitech G305 …",
  "price": { "display": "$29.99", "amount": 29.99 },
  "availability": "In Stock",
  "images": [ "…" ]
}
Pick one postcode per marketplace and keep it constant across a dataset. Changing it mid-crawl makes prices incomparable, because delivery cost and regional availability shift with it.

Marketplace codes

Two letters, case-insensitive, validated against ^[A-Za-z]{2}$. An unknown code returns 422 rather than silently falling back to US. See the marketplace list for all 16 and their matching postcode formats.

Pagination

Paginated endpoints take page, 1-based, and return has_next_page. There are no cursors to store.

Walking pages
page = 1
while True:
    data = fetch("/products/search", {"query": "wireless mouse", "page": page})
    yield from data["results"]
    if not data["has_next_page"]:
        break
    page += 1

On /products/search you can skip the loop entirely with limit — the API paginates server-side until it has N items. Each page it fetches still costs one credit, so limit=100 across five upstream pages costs five.

Booleans and filters

Booleans accept true/false, 1/0, yes/no and on/off. Anything else is a 422.

ParameterEndpointEffect
prime_only/products/searchDrop non-Prime results.
include_sponsored/products/searchSet false to strip sponsored placements — useful for organic rank tracking.
verified_only/products/reviewsOnly verified-purchase reviews.
min_price / max_price/products/searchPrice band in the marketplace's currency, not USD.

Sorting

/products/search accepts:

relevance price_asc price_desc rating newest bestseller

Validation errors

Bad input returns 422 with a detail array naming the offending field, so you can map errors back to form inputs without string matching.

422 Unprocessable Entity
{
  "detail": [
    {
      "loc": ["query", "asin"],
      "msg": "Field required",
      "type": "missing",
      "input": null
    }
  ]
}