Amazon Category Search From Top Node
Find Amazon sub-category markets under a top-level category, such as automotive or home & kitchen, with results sorted by sales volume from highest to lowest. Provide the top-level category ID or name obtained first via category_tree. You can select a marketplace and filter by average price, rating, ratings count, monthly sales volume, peak-season month, and sales-share ranges for new products, Amazon-owned products, Top-3 products, or Top-100 versus Top-400 products. New products here are products launched within 3 months; their sales share, Amazon-owned share, and Top-3 share are measured against Top-100 product sales. Price filters use local currency and sales-share filters use percentages from 0 to 100. Results are paginated in groups of 20, starting at page 1. This tool searches category markets rather than individual product listings.
Pricing
| Condition | Charge |
|---|---|
| Each call | 1 credits/call |
The marketplace, filters, and number of records returned do not affect the per-call charge. Fetching another page requires another call, charged separately.
Parameters
Optional parameters use the platform defaults when omitted.
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
page | integer | No | The page index of the query result. Defaults to page 1. Each page returns 20 records. | 1 |
amz_site | enum (Unknow | US | GB | DE | FR | IN | CA | JP | ES | IT | MX | AE | AU | BR | SA) | No | Amazon marketplace site. | Unknow |
top_node | string | Yes | Required: the top-level category to search (e.g. automotive, home & kitchen); the top-level node id or name must first be obtained via category_tree. | — |
price_max | number | No | Optional: filter sub-category markets whose average price (in local currency) is less than or equal to this value. | -9999 |
price_min | number | No | Optional: filter sub-category markets whose average price (in local currency, e.g. USD for the US site, EUR for the FR site) is greater than or equal to this value. | -9999 |
ratings_max | number | No | Optional: filter sub-category markets whose rating is less than or equal to this value. | -9999 |
ratings_min | number | No | Optional: filter sub-category markets whose rating is greater than or equal to this value. | -9999 |
ratings_count_max | integer | No | Optional: filter sub-category markets whose ratings count is less than or equal to this value. | -9999 |
ratings_count_min | integer | No | Optional: filter sub-category markets whose ratings count is greater than or equal to this value. | -9999 |
month_sales_volume_max | integer | No | Optional: filter sub-category markets whose monthly sales volume is less than or equal to this value. | -9999 |
month_sales_volume_min | integer | No | Optional: filter sub-category markets whose monthly sales volume is greater than or equal to this value. | -9999 |
seasonal_popular_product | enum (Both | January | February | March | April | May | June | July | August | September | October | November | December) | No | Optional: filter sub-categories whose peak season is the specified month. Allowed values: Both, January, February, March, April, May, June, July, August, September, October, November, December; defaults to Both. | Both |
newproduct_sales_share_max | number | No | Optional: expressed as a percentage from 0 to 100 (e.g. 40 means 40%). Filter sub-category markets whose new products launched within 3 months account for a share of Top-100 product sales less than or equal to this value. | -9999 |
newproduct_sales_share_min | number | No | Optional: expressed as a percentage from 0 to 100 (e.g. 40 means 40%). Filter sub-category markets whose new products launched within 3 months account for a share of Top-100 product sales greater than or equal to this value. | -9999 |
amazon_owned_sales_share_max | number | No | Optional: expressed as a percentage from 0 to 100 (e.g. 40 means 40%). Filter sub-category markets whose Amazon-owned sales share among Top-100 products is less than or equal to this value. | -9999 |
amazon_owned_sales_share_min | number | No | Optional: expressed as a percentage from 0 to 100 (e.g. 40 means 40%). Filter sub-category markets whose Amazon-owned sales share (seller concentration) among Top-100 products is greater than or equal to this value. | -9999 |
top3_product_sales_share_max | number | No | Optional: expressed as a percentage from 0 to 100 (e.g. 40 means 40%). Filter sub-category markets whose Top-3 product sales share among Top-100 products is less than or equal to this value. | -9999 |
top3_product_sales_share_min | number | No | Optional: expressed as a percentage from 0 to 100 (e.g. 40 means 40%). Filter sub-category markets whose Top-3 product sales share (sales concentration) among Top-100 products is greater than or equal to this value. | -9999 |
top100_top400_sales_share_max | number | No | Optional: expressed as a percentage from 0 to 100 (e.g. 40 means 40%). Filter sub-category markets whose Top-100 product sales as a share of Top-400 product sales is less than or equal to this value. | -9999 |
top100_top400_sales_share_min | number | No | Optional: expressed as a percentage from 0 to 100 (e.g. 40 means 40%). Filter sub-category markets whose Top-100 product sales as a share of Top-400 product sales (the lower the value, the deeper the long tail) is greater than or equal to this value. | -9999 |
Invocation example
Copy the request and explore its response example.
/agent-api/v1/tool/executeX-Api-Keycurl --request POST \
--url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_amazon_category_search_from_top_node' \
--header "X-Api-Key: $AGENTEARTH_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"amazon_owned_sales_share_max": 0.2,
"amz_site": "US",
"month_sales_volume_min": 3000,
"page": 1,
"price_max": 100,
"price_min": 25,
"top3_product_sales_share_max": 0.6,
"top_node": "383599011"
}
}'"No relevant data."
