Best-seller rankings for a category
best_sellersFetch ranked Amazon product listings by department, marketplace and page, returning resolved category names, subcategory ids and each product's rank.
Instructions
Best-seller rankings for a department of one marketplace, 50 per page. Every answer carries the department it resolved to and how (category_resolution: by slug, name or a fragment of a name, with a hint when a fragment such as 'shoes' landed on the whole 'Clothing, Shoes & Jewelry' department), available_categories (that marketplace's departments with slugs) and available_subcategories (the children of the node shown, with the ids subcategory_code takes). On amazon.com subcategory_code also takes any browse node id at any depth, or a name resolved under the department ("women's shoes", "mules & clogs"); category.subcategory_path gives the node's full path and category.heading the page's own title line. Price: $0.003 per call. No required parameters - calling it bare returns US appliances page 1. category accepts a slug, a display name, one of the older US department names, or a unique fragment; category_resolution.via says which, and a fragment match adds a hint naming the subcategories that carry the word, with ids. On amazon.com the whole browse tree is known: subcategory_code takes any node id or a name at any depth, subcategory_name and subcategory_path are filled without a fetch, and available_subcategories lists the node's real children (empty on a leaf). Other marketplaces name only what their navigation showed. page is capped at 5 (a 400 beyond, not a 500). rank is the position within the requested list on this page. Rows are the same for every marketplace; only the department vocabulary differs, and the answer carries it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| geo | No | Marketplace country code. | US |
| page | No | Result page, 1-based, 50 rows each; Amazon's lists stop at page 5. | |
| limit | No | How many ranked products to return from this page (0 = all of them). A full page is up to 48 rows and about 54 KB, which most clients spill to a file instead of showing inline. The answer carries _truncated with the true count when it trims. | |
| fields | No | Comma-separated row fields to return instead of the light set, e.g. "asin,product_title,product_price". Rows list what they left out under _omitted_fields. | |
| compact | No | Return light rows: identity, price, rating, badges and one delivery_date, dropping the long delivery prose that repeats itself across three fields. false returns every field the REST API sends (roughly 3x the size). | |
| category | No | Best-seller department, by slug or by name as Amazon shows it for that marketplace (case-insensitive; a unique fragment works, and the answer's category_resolution says when a fragment was used -- 'shoes' is the whole 'Clothing, Shoes & Jewelry' department, and the hint then lists the Shoes subcategories with their ids). Departments and their slugs differ per marketplace: amazon.com has electronics, amazon.de has ce-de (Electronics & Photo). Every answer lists that marketplace's departments under available_categories; an unknown or ambiguous name is a free 400 listing them. | appliances |
| subcategory_code | No | Browse node id under `category`: one from available_subcategories of a previous answer, or on amazon.com any node id at any depth (679410011 is Women > Shoes > Mules & Clogs) or a name resolved under the department ("women's shoes", "mens boots", "mules & clogs"). A name that fits two nodes equally (Men > Shoes > Boots and Women > Shoes > Boots) is a free 400 listing both ids with their paths. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| page | No | ||
| success | No | ||
| category | No | ||
| max_page | No | ||
| page_size | No | ||
| request_id | No | ||
| category_resolution | No | ||
| available_categories | No | ||
| available_subcategories | No |