openapi_v2_keyword_market_profile
Get keyword market profile
Function
Return six graded market dimensions with raw business evidence, observed ad coverage and annual seasonality at marketProfile.annualSeasonality for one or more keywords, using the latest available snapshot on or before date. Read level and interpretation for the category, and levelEvidence for the underlying values. Ad coverage is the fraction of distinct observed products seen in sponsored placements, not ad spend or impression share. No normalized scores are returned. Results preserve request keyword order in data.context + data.items[], including single-keyword requests.
Use cases
Compare demand, concentration, organic entry conditions, supply, brands and product benchmarks. Directions describe numeric meaning, not a recommendation to enter or avoid a market. Annual seasonality is a historical estimate of a keyword characteristic, independent of the selected trend window, and may change as history changes. Use trend-profile with windowPeriods for window-specific volatility; use detail for additional snapshot metrics and trend for raw weekly history.
Results and billing
Each request keyword keeps its position and identity.keyword in data.items. Only available dimensions and evidence are returned. An item without a profile contains only identity. Zero is a measured value; an empty peakPeriods array means no peak was identified in available evidence. Each item containing marketProfile costs one credit; identity-only items cost zero. Balance is prechecked for the requested keyword count; actual charge is in meta.creditsConsumedExact. context.resolvedDate is the actual snapshot date when known; dataWindow.currentPeriod is its period, not the historical range used by annual seasonality. Historical peaks do not imply yearly recurrence; non_seasonal may still include peakPeriods.
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": {
"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[KeywordMarketProfileData]",
"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 |
|---|---|---|---|
| date | Yes | Lookup date (YYYY-MM-DD). Returns the latest profile on or before this date; actual date is `resolvedDate`. | |
| keyword | No | Single keyword; mutually exclusive with `keywords`. Surrounding whitespace is trimmed; letter case is accepted. | |
| keywords | No | Keyword list, up to 20; mutually exclusive with `keyword`. Must equal `LOWER(TRIM(value))`; uppercase letters and surrounding whitespace are rejected. Duplicate keywords are rejected. | |
| granularity | No | Data period granularity. Only `week` is currently supported. | week |
| marketplace | No | Amazon marketplace code. Only 'US' is currently supported. | US |