Apiguru Amazon Data

Best-seller rankings for a category

best_sellers

Read-onlyIdempotent

Use for what sells best in a department right now. The rank is Amazon's, not a sales figure. 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, or 'subcategory' when a word such as 'camera' named a subcategory), available_categories (that marketplace's departments with slugs; MCP: with compact=false) 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

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). A word that names a subcategory works too: category=camera on amazon.es is Electronics > Camera & Photo (category_resolution.via says 'subcategory'; several equally good matches are a free 400 listing each as category + subcategory_code). REST answers list the marketplace's departments under available_categories (the MCP tool with compact=false); an unknown 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.

Changed1 schema field changedOct 2, 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, 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."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). A word that names a subcategory works too: category=camera on amazon.es is Electronics > Camera & Photo (category_resolution.via says 'subcategory'; several equally good matches are a free 400 listing each as category + subcategory_code). REST answers list the marketplace's departments under available_categories (the MCP tool with compact=false); an unknown name is a free 400 listing them."

Changed1 schema field changedOct 1, 2026

changedInput schema / properties / geo / enum

Previous value: -[
-  "US",
-  "CA",
-  "DE",
-  "MX",
-  "UK",
-  "FR",
-  "IT",
-  "ES",
-  "AU",
-  "BR",
-  "IN",
-  "JP",
-  "NL",
-  "AE",
-  "PL",
-  "SA",
-  "SG",
-  "SE",
-  "TR",
-  "BE"
-]New value: +[
+  "US",
+  "CA",
+  "DE",
+  "MX",
+  "UK",
+  "FR",
+  "IT",
+  "ES",
+  "AU",
+  "BR",
+  "IN",
+  "JP",
+  "NL",
+  "AE",
+  "PL",
+  "SA",
+  "SG",
+  "SE",
+  "TR",
+  "BE",
+  "IE",
+  "ZA",
+  "EG"
+]

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

A4.6/5.0

Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial extra context: per-call cost ($0.003), the page cap of 5 that yields a 400 rather than a 500, free 400 error semantics for ambiguous or unknown names, and truncation/omission behavior (_truncated, _omitted_fields). This is behavior beyond what the annotations or schema convey.

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

Conciseness3/5

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

The usage constraint is front-loaded, but the body is bloated and repeats itself – the amazon.com 'any browse node id at any depth / name resolved under the department' rule appears twice, and the category_resolution/available_categories explanation is restated in both description and per-parameter text. Dense, but not every sentence earns its 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?

With an output schema present, the description needn't detail return values, and it doesn't overreach. Given the 7 parameters, cross-marketplace vocabulary complexity, and pricing, the definition supplies everything an agent needs to call it correctly, including defaults, error behavior, and resolution semantics.

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

Parameters5/5

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

Although schema coverage is 100%, the description adds real meaning: it explains how fragments resolve (e.g. 'shoes' landing on the whole 'Clothing, Shoes & Jewelry' department), that amazon.com accepts any browse node id at any depth or a name, the subcategory ambiguity 400 behavior, and the default bare-call result. This goes well past restating the parameter docs.

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

Purpose5/5

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

The description states a specific verb and resource – 'Best-seller rankings for a department of one marketplace, 50 per page' – and immediately scopes it with 'The rank is Amazon's, not a sales figure.' An agent can distinguish this from sibling tools like search, deals, or product_details without opening the schema.

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

Usage Guidelines4/5

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

Opens with an explicit usage directive: 'Use for what sells best in a department right now.' It also explains the category-resolution paths and error fallbacks (free 400s listing alternatives). However, it never names or excludes a sibling tool (e.g. use search instead for keyword queries), so routing between tools is left to inference.

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.

Best-seller rankings for a category

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources