openapi_v2_markets_search
Markets Search V2
Search market data by category with aggregated demand, competition, and pricing metrics.
Use this to evaluate market size and competition before entering a niche. Example: search "Pet Supplies" with sampleAvgMonthlySalesMin >= 200 to find categories with proven demand. Data is based on top-100 product samples per category from the latest daily snapshot; results paginated (max 100 per page). Related: /products/search for product-level data in a category.
Responses:
200: Successful Response (Success Response) Content-Type: application/json
Example Response:
{
"success": true,
"meta": {
"requestId": "Requestid",
"timestamp": "Timestamp"
}
}Output Schema:
{
"properties": {
"success": {
"type": "boolean",
"title": "Success",
"description": "Whether the request was successful",
"default": true
},
"data": {
"title": "Data",
"description": "Response data payload"
},
"error": {
"description": "Error details if request failed"
},
"meta": {
"description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
"properties": {
"requestId": {
"type": "string",
"title": "Requestid",
"description": "Unique request identifier"
},
"timestamp": {
"type": "string",
"title": "Timestamp",
"description": "Response timestamp in ISO 8601 format"
},
"total": {
"title": "Total",
"description": "Total number of records"
},
"page": {
"title": "Page",
"description": "Current page number"
},
"pageSize": {
"title": "Pagesize",
"description": "Number of records per page"
},
"totalPages": {
"title": "Totalpages",
"description": "Total number of pages"
},
"creditsRemaining": {
"title": "Creditsremaining",
"description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
},
"creditsConsumed": {
"title": "Creditsconsumed",
"description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
},
"creditsRemainingExact": {
"title": "Creditsremainingexact",
"description": "Remaining API credits, precise to 1 decimal place"
},
"creditsConsumedExact": {
"title": "Creditsconsumedexact",
"description": "Credits consumed by this request, precise to 1 decimal place"
},
"tokensUsage": {
"description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
}
},
"type": "object",
"required": [
"requestId",
"timestamp"
],
"title": "ResponseMeta"
}
},
"type": "object",
"required": [
"meta"
],
"title": "OpenApiResponse[list[Market]]",
"examples": []
}422: Validation Error Content-Type: application/json
Example Response:
{
"detail": [
{
"loc": [],
"msg": "Message",
"type": "Error Type",
"ctx": {}
}
]
}Output Schema:
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| topN | No | Number of top products to analyze: '3', '5', '10', or '20'. Affects top* response fields (e.g., topAvgMonthlySales) | 10 |
| sortBy | No | Sort field (matches response field names) | sampleAvgMonthlyRevenue |
| pageSize | No | Page size | |
| dateRange | No | Aggregation window for metrics like monthly sales, revenue, and rating count. '30d' (default) — last 30 days. 'YYYY-MM' — that calendar month, e.g. '2026-04'. Available months: '2026-02' up to the most recent completed month. | 30d |
| sortOrder | No | Sort direction: asc or desc | desc |
| sampleType | No | Sampling method for market metrics: 'bySale100' = analyze top 100 products by sales volume, 'byBsr100' = top 100 by BSR rank, 'avg' = category-wide average | bySale100 |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |
| categoryPath | No | Category hierarchy from root. Example: ['Electronics', 'Computers', 'Laptops']. | |
| topAvgBsrMax | No | Maximum Top N average main-category BSR. | |
| topAvgBsrMin | No | Minimum Top N average main-category BSR. | |
| categoryKeyword | No | Filter by category name keyword (matches any level in category hierarchy, e.g., 'Electronics' or 'Laptops') | |
| sampleAvgBsrMax | No | Maximum sample average main-category BSR. | |
| sampleAvgBsrMin | No | Minimum sample average main-category BSR (lower = better). | |
| topSalesRateMax | No | Maximum Top N sales share as decimal. | |
| topSalesRateMin | No | Minimum Top N sales share as decimal. Example: 0.5 = 50%. | |
| newProductPeriod | No | Define 'new product' as listed within X months: '1', '3', '6', or '12'. Affects sampleNewSku* response fields | 3 |
| sampleAmzRateMax | No | Maximum sample Amazon-sold product rate as decimal. | |
| sampleAmzRateMin | No | Minimum sample Amazon-sold product rate as decimal. | |
| sampleFbaRateMax | No | Maximum sample FBA product rate as decimal. | |
| sampleFbaRateMin | No | Minimum sample FBA product rate as decimal. | |
| totalSkuCountMax | No | Maximum total SKU count in category. | |
| totalSkuCountMin | No | Minimum total SKU count in category. | |
| sampleAvgPriceMax | No | Maximum sample average price. | |
| sampleAvgPriceMin | No | Minimum sample average price. Example: 10.00. | |
| sampleSkuCountMax | No | Maximum sample SKU count. | |
| sampleSkuCountMin | No | Minimum sample SKU count. | |
| sampleAvgRatingMax | No | Maximum sample average star rating (0.0–5.0). | |
| sampleAvgRatingMin | No | Minimum sample average star rating (0.0–5.0). | |
| sampleBrandCountMax | No | Maximum sample unique brand count. | |
| sampleBrandCountMin | No | Minimum sample unique brand count. | |
| sampleNewSkuRateMax | No | Maximum sample new product rate as decimal. | |
| sampleNewSkuRateMin | No | Minimum sample new product rate as decimal. | |
| sampleNewSkuCountMax | No | Maximum sample new product count. | |
| sampleNewSkuCountMin | No | Minimum sample new product count. | |
| sampleSellerCountMax | No | Maximum sample unique seller count. | |
| sampleSellerCountMin | No | Minimum sample unique seller count. | |
| topBrandSalesRateMax | No | Maximum Top N brand concentration ratio as decimal. | |
| topBrandSalesRateMin | No | Minimum Top N brand concentration ratio as decimal. | |
| topAvgMonthlySalesMax | No | Maximum Top N average monthly sales. | |
| topAvgMonthlySalesMin | No | Minimum Top N average monthly sales. Units sold. | |
| topSellerSalesRateMax | No | Maximum Top N seller concentration ratio as decimal. | |
| topSellerSalesRateMin | No | Minimum Top N seller concentration ratio as decimal. | |
| sampleAvgRatingCountMax | No | Maximum sample average rating count per product. | |
| sampleAvgRatingCountMin | No | Minimum sample average rating count per product. | |
| sampleNewSkuAvgPriceMax | No | Maximum new product average price. | |
| sampleNewSkuAvgPriceMin | No | Minimum new product average price. | |
| topAvgMonthlyRevenueMax | No | Maximum Top N average monthly revenue. | |
| topAvgMonthlyRevenueMin | No | Minimum Top N average monthly revenue. | |
| sampleAvgMonthlySalesMax | No | Maximum sample average monthly sales. Units sold. | |
| sampleAvgMonthlySalesMin | No | Minimum sample average monthly sales. Units sold. Example: 100. | |
| sampleAvgPackageVolumeMax | No | Maximum sample average package volume in in³. | |
| sampleAvgPackageVolumeMin | No | Minimum sample average package volume in in³. | |
| sampleAvgPackageWeightMax | No | Maximum sample average package weight in oz. | |
| sampleAvgPackageWeightMin | No | Minimum sample average package weight in oz. | |
| sampleAvgMonthlyRevenueMax | No | Maximum sample average monthly revenue. | |
| sampleAvgMonthlyRevenueMin | No | Minimum sample average monthly revenue. Example: 5000.00. | |
| sampleNewSkuAvgMonthlySalesMax | No | Maximum new product average monthly sales. | |
| sampleNewSkuAvgMonthlySalesMin | No | Minimum new product average monthly sales. |