Apiguru Amazon Data

Best-seller rankings for a category

best_sellers

Read-onlyIdempotent

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.01 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

TableJSON 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

TableJSON 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

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 12, 2026

changedInput schema / properties / category / description

Previous value: -"Best-seller department, by slug or by name as Amazon shows it for that marketplace (case-insensitive; a unique fragment works). 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."New value: +"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."

changedInput schema / properties / subcategory_code / description

Previous value: -"Browse node id of a child of `category`, from available_subcategories of a previous answer for that category (a name from that list works too)."New value: +"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."

addedOutput schema / properties / category_resolution

Added value: +{
+  "default": null,
+  "title": "Category Resolution"
+}

Changed10 schema fields changedSep 8, 2026

changedInput schema / properties / category / description

Previous value: -"Category slug, lowercased by the server. Defaults to 'appliances'."New value: +"Best-seller department, by slug or by name as Amazon shows it for that marketplace (case-insensitive; a unique fragment works). 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."

changedInput schema / properties / page / description

Previous value: -"Result page, 1-based."New value: +"Result page, 1-based, 50 rows each; Amazon's lists stop at page 5."

addedInput schema / properties / page / maximum
```
Added value: +5
```

changedInput schema / properties / subcategory_code / description

Previous value: -"Optional subcategory node id to drill into."New value: +"Browse node id of a child of `category`, from available_subcategories of a previous answer for that category (a name from that list works too)."

addedOutput schema / properties / available_categories

Added value: +{
+  "default": null,
+  "title": "Available Categories"
+}

addedOutput schema / properties / available_subcategories

Added value: +{
+  "default": null,
+  "title": "Available Subcategories"
+}

addedOutput schema / properties / category

Added value: +{
+  "default": null,
+  "title": "Category"
+}

addedOutput schema / properties / max_page

Added value: +{
+  "default": null,
+  "title": "Max Page"
+}

addedOutput schema / properties / page

Added value: +{
+  "default": null,
+  "title": "Page"
+}

addedOutput schema / properties / page_size

Added value: +{
+  "default": null,
+  "title": "Page Size"
+}

First observedSep 5, 2026

TDQS

A3.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/idempotent/openWorld annotations, the description discloses cost ($0.01 per call), hard limits (page capped at 5, a 400 not a 500), truncation signals (_truncated, _omitted_fields), and the full shape of the response envelope (category_resolution, available_categories, available_subcategories). That is substantial operational context the annotations do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description repeats itself: the amazon.com any-depth node-id rule appears three times ('subcategory_code also takes any browse node id at any depth', 'the whole browse tree is known: subcategory_code takes any node id...') and the fragment-resolution hint is explained twice. The key routing information is buried mid-paragraph behind repeated asides, so several sentences do not earn their place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists and annotations cover the safety profile, the description still supplies everything needed to call it correctly: defaults, geography vocabulary differences, pagination ceiling, cost, and error semantics. Nothing material is missing for a zero-required-parameter ranking tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so baseline is 3, but the description adds real meaning: category accepts slug, display name, legacy US names, or a unique fragment with category_resolution.via reporting which; subcategory_code takes any browse-node id at any depth on amazon.com or a resolved name. The ambiguity 400 behavior is also explained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific resource ('Best-seller rankings for a department of one marketplace, 50 per page'), which is clearly distinct from a generic search or deals listing. It stops short of explicitly contrasting with siblings like search or deals, but the verb+resource+scope is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: 'No required parameters - calling it bare returns US appliances page 1' tells the agent how a default call behaves, and the free-400 behavior for unknown names steers recovery. There is no explicit 'use this instead of X when Y' guidance against the search or deals siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Apiguru Amazon Data tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.