apiwren
Amazon Data API · reference

Amazon Data API documentation

Everything you need to call Amazon Data API: how to authenticate, what every response looks like, how errors and rate limits work, and the parameters of all 17 endpoints. Every endpoint is a plain GET on https://amazon-data-api-search-product-reviews-best-sellers.p.rapidapi.com.

Get a free key on RapidAPIInteractive referenceOpenAPI spec

Authentication

Subscribe to a plan on RapidAPI (the free plan is enough to start) and copy your key. Send two headers with every request: X-RapidAPI-Key with your key and X-RapidAPI-Host with amazon-data-api-search-product-reviews-best-sellers.p.rapidapi.com.

A fresh request usually takes 3 to 6 seconds because it reads the live Amazon page, so set your client timeout to at least 60 seconds. Repeat requests within the cache window come back at once.

curl --request GET \
  --url 'https://amazon-data-api-search-product-reviews-best-sellers.p.rapidapi.com/product-details?asin=B088NRLMPV&country=US' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: amazon-data-api-search-product-reviews-best-sellers.p.rapidapi.com'
import os, requests

HOST = "amazon-data-api-search-product-reviews-best-sellers.p.rapidapi.com"

def amazon(path, **params):
    r = requests.get(
        f"https://{HOST}/{path}",
        params=params,
        headers={"X-RapidAPI-Key": os.environ["RAPIDAPI_KEY"], "X-RapidAPI-Host": HOST},
        timeout=60,
    )
    body = r.json()
    if "error" in body:
        raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
    if not r.ok:  # RapidAPI gateway errors, e.g. 429
        raise RuntimeError(body.get("message", f"HTTP {r.status_code}"))
    return body["data"]

print(amazon("product-details", asin="B088NRLMPV", country="US")["title"])
const HOST = 'amazon-data-api-search-product-reviews-best-sellers.p.rapidapi.com';

async function amazon(path, params) {
  const res = await fetch(`https://${HOST}/${path}?${new URLSearchParams(params)}`, {
    headers: { 'X-RapidAPI-Key': process.env.RAPIDAPI_KEY, 'X-RapidAPI-Host': HOST },
  });
  const body = await res.json();
  if (body.error) throw new Error(`${body.error.code}: ${body.error.message}`);
  if (!res.ok) throw new Error(body.message ?? `HTTP ${res.status}`); // RapidAPI gateway errors, e.g. 429
  return body.data;
}

console.log((await amazon('product-details', { asin: 'B088NRLMPV', country: 'US' })).title);
// npm install amazon-data-api
import { AmazonData } from 'amazon-data-api';

const amazon = new AmazonData({ apiKey: process.env.RAPIDAPI_KEY });
const { data } = await amazon.productDetails({ asin: 'B088NRLMPV', country: 'US' });
console.log(data.title); // errors throw AmazonDataError with code and status

Responses

A successful response has data, whose shape depends on the endpoint, and meta. meta.country is the marketplace, meta.cached says whether the result came from cache, and meta.fetched_at says when the Amazon page was read.

An error has error with a code and a message instead of data. A response never has both, so check for error in the body rather than relying on the HTTP status alone.

200 OK · data
{
  "data": {
    "asin": "B088NRLMPV",
    "title": "…"
  },
  "meta": {
    "country": "US",
    "cached": false,
    "fetched_at": "2026-11-04T09:00:00.000Z"
  }
}
200 OK · error
{
  "error": {
    "code": "invalid_input",
    "message": "asin must be 10 characters, letters and digits only"
  }
}

Errors and retries

Problems with the request itself come back with HTTP 200 and an error body. Problems on our side or Amazon’s use 5xx. RapidAPI’s own gateway answers 429 when you go over your plan’s rate limit.

HTTPcodeWhat happenedWhat to do
200invalid_inputA parameter is missing or malformed; the message names it.Fix the request. Don’t retry.
200country_unavailableUnknown marketplace code, or the endpoint is switched off for that marketplace.Use another marketplace. GET /health lists what is switched off.
200not_foundAmazon has no page for this ASIN, seller, category or handle in that marketplace.Check the ID and the country.
200sign_in_requiredAmazon shows this page only to signed-in visitors.Don’t retry.
429—Over your plan’s per-minute rate limit. Sent by RapidAPI with a message field.Wait a few seconds, then retry.
503busyToo many requests at once on our side.Wait Retry-After seconds, then retry.
502upstream_failed, wrong_marketplace, parse_failedAmazon could not be reached, sent another country’s page, or sent a page we could not read.Retry after a few seconds.
500upstream_failedUnexpected error.Retry after a few seconds.

A retry rule that covers everything: retry 429, 500, 502 and 503 up to 3 times, waiting Retry-After seconds when it is sent and 2, 4, then 8 seconds otherwise. Never retry a response that carries an error with HTTP 200.

Rate limits and overage

Billed monthly by RapidAPI. The free Basic plan includes 100 requests a month. Prices as listed on RapidAPI on .

PlanPrice a monthRequests a monthOver quotaRate limit
Basic$0100Hard limit10 a minute
Pro$1515,000$0.003 a request120 a minute
Ultra$4975,000$0.002 a request300 a minute
Mega$129300,000$0.001 a request600 a minute

The rate limit is per API key. Paid plans keep working after the monthly quota is used up, and each extra request is billed at the overage price on your RapidAPI invoice. The free Basic plan stops at its quota.

Endpoints

Every endpoint takes country, a marketplace code such as US, DE or JP (default US). Each endpoint has its own page with an example request and a recorded response.

GET /product-details · Product details by ASIN

Everything public on the product page: title, brand, price, list price, images, rating, ratings count, availability, badges, bullet points, description, product details table, category breadcrumbs, Best Sellers Rank, "bought in past month" and whether the product has variations. `is_prime` is true when Amazon shows a Prime badge; null when unknown (logged-out pages rarely show Prime). `original_price_type` is the page's label for the original price, e.g. "Print List Price" on Kindle pages.

NameRequiredValuesNotes
asinyesmatches ^[A-Za-z0-9]{10}$10-character Amazon product ID (ASIN). Case and surrounding spaces are ignored.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com).
Example request and response for /product-details

GET /product-reviews · Ratings and review highlights

Public review data from the product page: average rating, total ratings, star breakdown (% per star), Amazon's AI "Customers say" summary with topic tags and mention counts, and the top reviews Amazon shows logged-out visitors (typically 5 to 13; may be empty on some amazon.com pages, where Amazon asks visitors to sign in). Full review lists need an Amazon login and are not included. A product nobody has rated yet returns rating null and total_ratings 0. Each review has `date` (ISO YYYY-MM-DD or null) and `date_text` (Amazon's raw line), `helpful_votes` (integer or null) and `helpful_votes_text` (Amazon's raw phrase). Aspect names use display casing, e.g. "Value for money".

NameRequiredValuesNotes
asinyesmatches ^[A-Za-z0-9]{10}$10-character Amazon product ID (ASIN). Case and surrounding spaces are ignored.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). The playground starts on GB because amazon.com often hides reviews from signed-out visitors; leave country out and the API uses US.
Example request and response for /product-reviews

GET /best-sellers · Best sellers and rankings

Amazon's ranked lists for a category: Best Sellers, New Releases, Movers & Shakers, Most Wished For and Gift Ideas. 50 ranks per page, 2 pages per list. Full details for the items Amazon renders (about the first 30); the rest return rank, ASIN and URL. A list Amazon reports as empty ("no ... available in this category") returns items: []. type=movers-and-shakers is currently unavailable: Amazon shows it only to signed-in visitors, and returns 400 invalid_input.

NameRequiredValuesNotes
categoryyesstringCategory slug as in Amazon's best-seller URLs, optionally with a node ID: electronics or electronics/172541.
typenobestsellers, new-releases, movers-and-shakers, most-wished-for, gift-ideas (default bestsellers)bestsellers (default), new-releases, most-wished-for, gift-ideas. movers-and-shakers is currently unavailable: Amazon shows it only to signed-in visitors (returns 400 invalid_input).
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com).
pageno1, 2 (default 1)1 = ranks 1 to 50, 2 = ranks 51 to 100.
Example request and response for /best-sellers

GET /seller-products · Products sold by a seller

Lists the products one third-party seller offers on one Amazon marketplace, from the seller's storefront. Returns the same result fields as /search (position, ASIN, title, price, list price, rating, ratings count, flags). Find a seller ID in the URL of the seller's page (seller=...) or in a product page's offers. Not available on ZA.

NameRequiredValuesNotes
seller_idyesmatches ^[A-Za-z0-9]{10,16}$Amazon seller ID, 10 to 16 letters and digits.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). Not available on ZA (returns 400 country_unavailable).
pageno1 to 20 (default 1)
sortnorelevance, price_asc, price_desc, reviews, newest, bestsellers
Example request and response for /seller-products

GET /product-lookup · Look up a product by barcode

Searches one Amazon marketplace for a UPC, EAN, ISBN or GTIN and returns the organic search results, best match first, with sponsored results removed. Same result fields as /search. Matches are not verified against the barcode: search cards carry no barcode, so check the top result before relying on it (call /product-details with its ASIN). If Amazon searched for something other than the code (it corrected the query), results is [].

NameRequiredValuesNotes
identifieryesstringUPC, EAN, ISBN or GTIN: 8, 10, 12, 13 or 14 digits (ISBN-10 may end in X). Hyphens and spaces are ignored.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com).
Example request and response for /product-lookup

GET /product-offers · All seller offers for a product

Every offer Amazon shows for one ASIN on one marketplace: the featured (pinned) offer first, then the other sellers, each with condition, price, list price, seller name, ID and rating, ships-from, sold/fulfilled by Amazon, and delivery text. Null where Amazon shows no value. offers is [] when Amazon lists none. total_offers is Amazon's count of offers besides the pinned one (null on page 2 and later, which list only the next sellers, about 10 per page; the pinned offer is returned on page 1 only). Every response is checked to come from the requested marketplace; a page from another country is never returned.

NameRequiredValuesNotes
asinyesmatches ^[A-Za-z0-9]{10}$10-character Amazon product ID (ASIN). Case and surrounding spaces are ignored.
pageno1 to 20 (default 1)Page of other offers, 1 to 20. Default 1.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com).
Example request and response for /product-offers

GET /deals · Today's deals

The first page of Amazon's Today's Deals for one marketplace (about 30 deals), each with deal ID, ASIN, title, image, deal price, list price, savings percent, Amazon's deal badge text, percent claimed and end time. Null where Amazon shows no value; ends_at is usually null because the deals page does not publish end times. Only page 1 is available: Amazon serves the same deals for later pages. Every response is checked to come from the requested marketplace; a page from another country is never returned.

NameRequiredValuesNotes
pageno1 to 1 (default 1)Only 1 is accepted: Amazon serves the same deals for later pages.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com).
Example request and response for /deals

GET /seller-profile · Seller profile

Public profile of one third-party seller on one marketplace: name, business name and address, storefront link, logo, rating out of 5, percent positive and number of ratings in the last 12 months, lifetime ratings and the star breakdown in percent. Null where Amazon shows no value. Every response is checked to come from the requested marketplace; a page from another country is never returned. Marketplaces where the seller page cannot be read return 400 country_unavailable.

NameRequiredValuesNotes
seller_idyesmatches ^[A-Za-z0-9]{10,16}$Amazon seller ID, 10 to 16 letters and digits.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). Not available on IE, SG, ZA (returns 400 country_unavailable).
Example request and response for /seller-profile

GET /categories · Best-seller categories

The category tree of Amazon's Best Sellers for one marketplace: the top-level departments, or the subcategories of one category. Each entry has the category name, its node ID (null for a department), a `path` and the best-sellers URL. `path` is exactly what `/best-sellers` and `/categories` accept as `category`. A category with no subcategories returns an empty list. Names come in the marketplace language. `parent` echoes the requested category, or null for the top level. Every response is checked to come from the requested marketplace; a page from another country is never returned.

NameRequiredValuesNotes
categorynostringA `path` from a previous response: a department slug (electronics) or slug and node ID (electronics/172541). Omit for the top-level departments.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com).
Example request and response for /categories

GET /search-autocomplete · Search autocomplete

The suggestions Amazon's search box offers for a prefix on one marketplace, in Amazon's order, as plain strings. `query` echoes the prefix. An empty `suggestions` list is a valid answer. Suggestions come in the marketplace language.

NameRequiredValuesNotes
queryyesstringThe text typed so far, 1 to 100 characters.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). Not available on IN (returns 400 country_unavailable).
Example request and response for /search-autocomplete

GET /products-by-category · Products in a category

Lists the products Amazon shows for a category with no search keyword, one page at a time. Takes the same category values as /search: a search alias such as electronics, or a numeric browse node ID. Returns the same result fields as /search.

NameRequiredValuesNotes
categoryyesmatches ^[A-Za-z0-9-]+$Amazon search category alias (e.g. electronics) or numeric browse node ID (e.g. 172282). Same values as /search.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com).
pageno1 to 20 (default 1)
sortnorelevance, price_asc, price_desc, reviews, newest, bestsellers
Example request and response for /products-by-category

GET /seller-reviews · A seller's buyer feedback

Buyer feedback for one third-party seller, newest first: star rating, comment, rater name, date (YYYY-MM-DD plus Amazon's original text), and whether Amazon struck the feedback through with its reason. The first call returns the newest feedback (usually 5 entries); pass `next_cursor` back as `cursor` for the next page. `next_cursor` is null on the last page. Every response is checked to come from the requested marketplace. Marketplaces where the seller page cannot be read return 400 country_unavailable.

NameRequiredValuesNotes
seller_idyesmatches ^[A-Za-z0-9]{10,16}$Amazon seller ID, 10 to 16 letters and digits.
cursornostringThe `next_cursor` value from the previous response. Omit it for the first page.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). Not available on BE, IE, SG, ZA (returns 400 country_unavailable).
Example request and response for /seller-reviews

GET /promo-code-details · Promotion details

An Amazon promotion by its ID (the code in an amazon.com/promotion/psp/<promo_id> link, shown on product pages next to coupons and 'Buy more & save' offers): title, banner, schedule, how-to-claim steps, the note under them and the seller running it. The promotion's product list is not returned: Amazon loads it only in the browser. Every response is checked to come from the requested marketplace. An unknown or ended promotion returns 404 not_found.

NameRequiredValuesNotes
promo_idyesmatches ^[A-Za-z0-9]{8,20}$The promotion ID from an amazon.com/promotion/psp/<promo_id> link.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com).
Example request and response for /promo-code-details

GET /influencer-profile · Influencer storefront profile

An Amazon influencer's storefront profile by handle: display name, bio, profile image, top-creator badge, social links and the trending products on the storefront (ASIN, image, price, deal flag). Every response is checked to come from the requested marketplace. An unknown handle returns 404 not_found.

NameRequiredValuesNotes
handleyesmatches ^[A-Za-z0-9][A-Za-z0-9._-]{1,63}$The storefront name from amazon.com/shop/<handle>.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). Not available on MX, BR, GB, SA, EG, JP, IE, ZA (returns 400 country_unavailable).
Example request and response for /influencer-profile

GET /influencer-posts · Influencer video posts

The newest video posts (up to 10) on an Amazon influencer's storefront: title, duration, thumbnail, stream URL, post link and the ASINs of the products each video features. Photo and idea-list posts are not included: Amazon loads them only in the browser. An unknown handle returns 404 not_found.

NameRequiredValuesNotes
handleyesmatches ^[A-Za-z0-9][A-Za-z0-9._-]{1,63}$The storefront name from amazon.com/shop/<handle>.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAAmazon marketplace, as an ISO country code. GB is amazon.co.uk. Default US (amazon.com). Not available on MX, BR, GB, SA, EG, JP, IE, ZA (returns 400 country_unavailable).
Example request and response for /influencer-posts

GET /scrape-url · Any Amazon page as HTML

The HTML of any page on one of the 23 Amazon marketplaces, for data the other endpoints don't parse. The marketplace comes from the URL's domain; pass `country` only to double-check it. Not parsed: you get `{ url, html }`. Pages Amazon shows only to signed-in visitors return 403 sign_in_required, and a page that came back from another marketplace returns 502 wrong_marketplace.

NameRequiredValuesNotes
urlyesstringA full URL on www.amazon.com, www.amazon.co.uk, www.amazon.de or another of the 23 marketplaces.
countrynoUS, CA, MX, BR, GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, JP, SG, AU, IE, ZAOptional check: when given, it must be the marketplace of the url's domain, else 400 invalid_input.
Example request and response for /scrape-url