1. Function
Find a paginated list of US Amazon category markets. Each data[] row contains the category identity and current market measures grouped by statistical scope. data[].marketTotal contains full-category measures; data[].marketSample contains selected Top 100 sales, per-product averages and competition. productTopNMetrics[] and brandTopNMetrics[] each have one row for N=3/5/10/20. Both return avgBsr, avgMonthlySales, avgMonthlyRevenue, monthlySales, monthlyRevenue, monthlySalesRate and monthlyRevenueRate. Product rows also return productTopN and topNSkuCount; brand rows return brandTopN and topNBrandCount. Each row selects the leading products or brands by monthly unit sales; productTopN and brandTopN are rank cutoffs, topNSkuCount is the actual number of selected products, and topNBrandCount is the actual number of selected brands. Brand averages are per product in the selected brands. Both statistical scopes return newProductMetrics[] for 1/3/6/12 calendar-month windows. marketTotal returns new-SKU count, share of all category SKUs, monthly sales, and monthly revenue for each window; marketSample additionally returns averages and shares. meta.total is the number of matching markets.
2. Use cases
Use search to compare markets by size, per-product sales, price, BSR, package weight or volume, ratings, gross margin, fulfillment, new-product performance or Top N concentration in one call. All filters apply before pagination. topN selects the group used by generic Top N filters; newProductPeriod selects the window used by generic new-product filters and sorting. Neither selector limits the response arrays. Sample sales and revenue filters use per-product averages so markets with different actual sample counts remain comparable. Use category.ids to select multiple market rows by category ID. category.includeDescendantCategoryProducts controls whether each row's product metrics include descendant categories and defaults to true. Alternatively, use a complete category.path or exact category.name; omit all locators to search every market. category.name filters by the exact node name and may return multiple market IDs. For fuzzy category discovery, use /categories. Use structure-profile for its distributions or history for its time series.
3. Example
Call with {"category":{"ids":["1045564","1234567"],"includeDescendantCategoryProducts":true},"filters":{"sampleAvgMonthlySalesMin":1500,"sampleAvgGrossMarginRateMin":0.2,"topNProductMonthlySalesRateMax":0.5},"sampleType":"unitSalesTop100","topN":"10","newProductPeriod":"3","page":1}. Read data[].categoryId, data[].marketTotal.monthlySales, data[].marketTotal.newProductMetrics[], data[].marketSample.avgMonthlySales, data[].marketSample.productTopNMetrics[], data[].marketSample.brandTopNMetrics[], data[].marketSample.newProductMetrics[] and meta.total.
4. Data range
US only. Each category ID yields its own market row. By default, its product measures include products assigned directly to the category and its descendants without duplicates; set category.includeDescendantCategoryProducts=false to count only directly assigned products. Top 100 is selected by monthly unit sales or revenue. If date is omitted, the latest available snapshot is used; data[].date gives its actual date. category.path resolves the complete path to one category ID before search; category.name matches the node name exactly. Historical flat requests, including categoryKeyword, remain accepted through Pydantic. New requests use /categories for fuzzy name discovery. Legacy dateRange remains accepted but is not part of the published request schema. Top N and new-product filters use topN and newProductPeriod respectively. Gross-margin rates use decimals from 0 to 1; monetary filters use USD.
5. New-product definition
For each newProductMetrics[] item with periodMonths=N, a product is new only when its business launch date is later than data.date minus N calendar months and no later than data.date. The business launch date prefers Amazon Date First Available; when unavailable, it uses the earliest valid SKU first-observed date, SKU first-review date, or parent-product first-review date. A missing business launch date is not classified as new; the product still remains in the product-count denominator. Search returns all four windows so an Agent can compare short- and long-window new-product activity without additional calls.
ConnectorNo auth