Keyword Research
Use the Keyword Research API for Amazon keyword research. Review request parameters, response fields, and runnable examples.
/v1 /amazon /keywords /researchAPI data samples
Inspect the request body and complete response shape used by this endpoint.
{
"keywords": "child",
"marketplace": "US",
"month": "202507",
"page": 1,
"size": 1
}{
"request_id": "8fb43e59-4ff9-4dc8-a4b7-2ed164e45ab8",
"data": {
"guestId": null,
"pages": 1239,
"page": 1,
"size": 1,
"total": 1239,
"took": 15,
"url": null,
"order": {
"field": "",
"desc": true
},
"items": [
{
"marketplace": "US",
"keywords": "child",
"searches": 17702,
"purchases": 2436,
"growth": -19.83153,
"purchaseRate": 0.1376,
"products": 364623,
"supplyDemandRatio": 0.05,
"searchDepartments": [
{
"code": "hpc",
"label": "Health, Household & Baby Care",
"total": 2725,
"ratio": 0.15393741
}
],
"month": "2025.07",
"supplement": "N",
"searchMonthlyCv": -12649,
"searchMonthlyCr": -41.68,
"searchNearlyCv": -4379,
"searchNearlyCr": -19.83,
"currency": "$",
"avgPrice": 17.97,
"avgRatings": 25985,
"avgRating": 4.8,
"relationAsinList": [
{
"asin": "B06XSCPJZK",
"imageUrl": "https://m.media-amazon.com/images/I/41dfAc5LCkL._AC_US200_.jpg",
"price": 26.59,
"ratings": 6816,
"rating": 4.4
}
],
"bidMin": 0.91,
"bidMax": 1.4,
"bid": 1.26,
"araAsinList": [
{
"asin": "B07HQ2JS3L",
"title": null,
"imageUrl": null,
"clickRate": 0.28,
"conversionShareRate": 0
}
],
"araClickRate": 0.6205,
"araShareRate": 0,
"goodsValue": 0.0701,
"marketPeriod": "S9,S10",
"brand": null,
"hasBrandWord": false,
"keywordCn": "孩子",
"brands": [
"Majosta"
],
"categories": [
"Digital_Video_Download"
],
"titleDensityExact": 3
}
],
"terminal": null,
"hasNextPage": null,
"guestVisited": false
}
}Availability: Available
This endpoint is active in the v1 gateway, OpenAPI, and subscription catalog. A successful call consumes 1 billing unit.
POST /v1/amazon/keywords/research
The request and response fields below match the current public contract.
Quick call
First create an API key, then store it in a server-side environment variable:
export ECOMMERCE_DATA_API_KEY="your_api_key"curl --request POST \
--url https://ecommercedataapi.com/v1/amazon/keywords/research \
--header "Content-Type: application/json" \
--header "X-API-Key: ${ECOMMERCE_DATA_API_KEY}" \
--data '{
"keywords": "child",
"marketplace": "US",
"month": "202507",
"page": 1,
"size": 1
}'Integrate with an AI CLI
Copy for your AI CLI
Paste this task into Codex, Claude Code, Gemini CLI, or another coding agent.
Integrate the "Keyword Research" endpoint from Ecommerce Data API into the current repository. Make the changes directly instead of only returning sample code.
API documentation: https://ecommercedataapi.com/en/docs/amazon/keywords/research
Endpoint: POST https://ecommercedataapi.com/v1/amazon/keywords/research
API key environment variable: ECOMMERCE_DATA_API_KEY
Example request:
{
"keywords": "child",
"marketplace": "US",
"month": "202507",
"page": 1,
"size": 1
}
Requirements:
1. Read the API documentation first, then inspect the repository's language, framework, HTTP client, directory structure, and environment-variable conventions.
2. Reuse the existing API client and error-handling patterns. If none exist, add the smallest reusable Ecommerce Data API client and an endpoint-specific wrapper.
3. Read the key from the server-side ECOMMERCE_DATA_API_KEY environment variable and send Content-Type: application/json plus the X-API-Key header. Never write a real key into source code, browser code, logs, test snapshots, or Git.
4. If the environment variable is missing, tell me to configure ECOMMERCE_DATA_API_KEY myself. Do not request, print, or invent the real key, and continue implementing code and tests that do not require a live request.
5. Implement request and response types from the documentation. Handle non-2xx responses, request_id, error.code, error.message, and 429 rate limits.
6. Add a minimal usage example or test that follows the repository's conventions. Run one minimal live request only when the key is already configured and external requests are allowed; otherwise use mocks or static validation.
7. Run the relevant formatter, type checker, and tests. Report changed files, usage, verification results, and any environment variable I still need to configure.Open this request in Postman
Download the preconfigured collection for this endpoint, then import it into Postman.
Node.js example
const response = await fetch(
'https://ecommercedataapi.com/v1/amazon/keywords/research',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': process.env.ECOMMERCE_DATA_API_KEY,
},
body: JSON.stringify({
keywords: 'child',
marketplace: 'US',
month: '202507',
page: 1,
size: 1,
}),
}
);
const result = await response.json();
if (!response.ok) {
throw new Error(`${result.error?.code}: ${result.error?.message}`);
}
console.log(result.data);Python example
import os
import requests
response = requests.post(
"https://ecommercedataapi.com/v1/amazon/keywords/research",
headers={
"Content-Type": "application/json",
"X-API-Key": os.environ["ECOMMERCE_DATA_API_KEY"],
},
json={
"keywords": "child",
"marketplace": "US",
"month": "202507",
"page": 1,
"size": 1,
},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])Request body
Send the fields below directly in the JSON body without an extra wrapper. Undefined fields are rejected.
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
departments | Array | No | Departments. | ["automotive","baby-products"] |
excludeKeywords | String | No | Exclude keywords. | portable |
keywords | String | No | Keywords used by the query. | N95 |
marketPeriod | String | No | Market period. | Market period |
marketplace | String | Yes | Amazon marketplace code. Supported values are listed in the schema. | US |
maxAraClickRate | Number | No | Max ara click rate. Maximum value. | 56.4 |
maxAvgPrice | Number | No | Max avg price. Maximum value. | 30.3 |
maxBid | Number | No | Max bid. Maximum value. | 10.6 |
maxGoodsValue | Number | No | Max goods value. Maximum value. | 41.1 |
maxProducts | Integer | No | Max products. Maximum value. | 90 |
maxPurchaseRate | Number | No | Max purchase rate. Maximum value. Percentage or ratio value as documented. | 10.5 |
maxPurchases | Integer | No | Max purchases. Maximum value. | 500 |
maxRating | Number | No | Max rating. Maximum value. | 4.1 |
maxRatings | Integer | No | Max ratings. Maximum value. | 3000 |
maxSearchMonthCr | Number | No | Max search month change rate. Maximum value. Percentage or ratio value as documented. | 30.1 |
maxSearchMonthCv | Integer | No | Max search month change value. Maximum value. | 3000 |
maxSearchNearlyCr | Number | No | Max search nearly change rate. Maximum value. Percentage or ratio value as documented. | 20.4 |
maxSearchNearlyCv | Integer | No | Max search nearly change value. Maximum value. | 20000 |
maxSearches | Integer | No | Max searches. Maximum value. | 300 |
maxSearchesCr | Number | No | Max searches change rate. Maximum value. Percentage or ratio value as documented. | 50.8 |
maxSupplyDemandRatio | Number | No | Max supply demand ratio. Maximum value. | 10.4 |
maxWordCount | Integer | No | Max word count. Maximum value. | 3 |
minAraClickRate | Number | No | Min ara click rate. Minimum value. | 20.1 |
minAvgPrice | Number | No | Min avg price. Minimum value. | 20 |
minBid | Number | No | Min bid. Minimum value. | 6.2 |
minGoodsValue | Number | No | Min goods value. Minimum value. | 10.1 |
minProducts | Integer | No | Min products. Minimum value. | 10 |
minPurchaseRate | Number | No | Min purchase rate. Minimum value. Percentage or ratio value as documented. | 3.2 |
minPurchases | Integer | No | Min purchases. Minimum value. | 100 |
minRating | Number | No | Min rating. Minimum value. | 3.2 |
minRatings | Integer | No | Min ratings. Minimum value. | 2000 |
minSearchMonthCr | Number | No | Min search month change rate. Minimum value. Percentage or ratio value as documented. | 5.3 |
minSearchMonthCv | Integer | No | Min search month change value. Minimum value. | 1000 |
minSearchNearlyCr | Number | No | Min search nearly change rate. Minimum value. Percentage or ratio value as documented. | 10.3 |
minSearchNearlyCv | Integer | No | Min search nearly change value. Minimum value. | 6000 |
minSearches | Integer | No | Min searches. Minimum value. | 100 |
minSearchesCr | Number | No | Min searches change rate. Minimum value. Percentage or ratio value as documented. | 10 |
minSupplyDemandRatio | Number | No | Min supply demand ratio. Minimum value. | 5.6 |
minWordCount | Integer | No | Min word count. Minimum value. | 1 |
month | String | No | Data month. Use the format documented for this endpoint, usually yyyyMM. | 202203 |
order | Object | No | Sort definition. | {} |
order.desc | Boolean | No | Use true for descending order or false for ascending order. | true |
order.field | String | No | Field used to sort the results. | searches |
page | Integer | No | Page number starting at 1. | 1 |
returnFields | String | No | Optional comma-separated response fields. Omit it to receive the standard payload. | marketplace,keywords,searches |
size | Integer | No | Number of results per page. | 20 |
withYearlyGrowth | Boolean | No | With yearly growth. | false |
Response structure
| Field | Type | Description |
|---|---|---|
request_id | String | Unique identifier for this request. |
data | Object | Endpoint business data. |
The fields below are inside data. For array endpoints they describe one array item; for paginated endpoints they describe one record in items[].
Response fields
| Field | Type | Description | Example |
|---|---|---|---|
marketplace | String | Marketplace. | US |
keywords | String | Keywords. | polaroid cameras |
searches | Integer | Searches. | 141356 |
clicks | String | Clicks. | 在某个关键词搜索结果页中被点击的总次数非单个ASIN在关键词下的点击量 |
impressions | String | Impressions. | 在某个关键词搜索结果页中所有ASIN的总展示次数非单个ASIN在关键词下的曝光量 |
purchases | Integer | Purchases. | 4029 |
growth | Number | Growth. Percentage or ratio value as documented. | -25.482092 |
purchaseRate | Number | Purchase rate. Percentage or ratio value as documented. | 0.0285 |
products | Integer | Products. | 173 |
supplyDemandRatio | Number | Supply demand ratio. | 817.09 |
searchDepartments | Array | Search departments. | - |
searchDepartments.code | String | Code. | electronics |
searchDepartments.label | String | Label. | Electronics |
searchDepartments.total | Integer | Total. | 141356 |
searchDepartments.ratio | Number | Ratio. Percentage or ratio value as documented. | 1 |
month | String | Month. | 2022.01 |
supplement | String | Supplement. | N |
searchMonthlyCv | Integer | Search monthly change value. | 139749 |
searchMonthlyCr | Number | Search monthly change rate. Percentage or ratio value as documented. | 8696.27 |
searchNearlyCv | Integer | Search nearly change value. | -48338 |
searchNearlyCr | Number | Search nearly change rate. Percentage or ratio value as documented. | -25.48 |
currency | String | Currency. | $ |
avgPrice | Number | Avg price. | 116.24 |
avgRatings | Integer | Avg ratings. | 2584 |
avgRating | Number | Avg rating. | 4.5 |
relationAsinList | Array | Relation ASIN list. | 4.8 |
relationAsinList.price | Number | Price. | 59.95 |
relationAsinList.ratings | Integer | Ratings. | 20115 |
relationAsinList.rating | Number | Rating. | 4.7 |
bidMin | Number | Bid min. Minimum value. | 0.987 |
bidMax | Number | Bid max. Maximum value. | 2.54 |
bid | Number | Bid. | 1.26 |
araClickRate | Number | Ara click rate. Percentage or ratio value as documented. | 0.2633 |
araShareRate | Number | Ara share rate. Percentage or ratio value as documented. | 0.2633 |
araAsinList | Array | Ara ASIN list. | - |
araAsinList.asin | String | ASIN. | B099VDRGG1 |
araAsinList.title | String | Title. | Fujifilm Instax Mini 9 |
araAsinList.imageUrl | String | Image URL. | https://m.media-amazon.com/images/I/51aZiZaicYL._AC_US200_.jpg |
araAsinList.clickRate | Number | Click rate. Percentage or ratio value as documented. | 0.116 |
araAsinList.conversionShareRate | Number | Conversion share rate. Percentage or ratio value as documented. | 0.1217 |
goodsValue | Number | Goods value. | 0.0108 |
brands | Array | Brands. | ["LEGO","Jorumo","Nifeliz"] |
categories | Array | Categories. | ["Toys","Home","Mobile_Apps"] |
titleDensityExact | String | Title density exact. | 21 |
marketPeriod | String | Market period. | S11,S12 |
brand | String | Brand. | Fujifilm |
hasBrandWord | Boolean | Has brand word. | false |
keywordCn | String | Keyword cn. | 宝丽来相机 |
Response example
{
"request_id": "8fb43e59-4ff9-4dc8-a4b7-2ed164e45ab8",
"data": {
"guestId": null,
"pages": 1239,
"page": 1,
"size": 1,
"total": 1239,
"took": 15,
"url": null,
"order": {
"field": "",
"desc": true
},
"items": [
{
"marketplace": "US",
"keywords": "child",
"searches": 17702,
"purchases": 2436,
"growth": -19.83153,
"purchaseRate": 0.1376,
"products": 364623,
"supplyDemandRatio": 0.05,
"searchDepartments": [
{
"code": "hpc",
"label": "Health, Household & Baby Care",
"total": 2725,
"ratio": 0.15393741
}
],
"month": "2025.07",
"supplement": "N",
"searchMonthlyCv": -12649,
"searchMonthlyCr": -41.68,
"searchNearlyCv": -4379,
"searchNearlyCr": -19.83,
"currency": "$",
"avgPrice": 17.97,
"avgRatings": 25985,
"avgRating": 4.8,
"relationAsinList": [
{
"asin": "B06XSCPJZK",
"imageUrl": "https://m.media-amazon.com/images/I/41dfAc5LCkL._AC_US200_.jpg",
"price": 26.59,
"ratings": 6816,
"rating": 4.4
}
],
"bidMin": 0.91,
"bidMax": 1.4,
"bid": 1.26,
"araAsinList": [
{
"asin": "B07HQ2JS3L",
"title": null,
"imageUrl": null,
"clickRate": 0.28,
"conversionShareRate": 0
}
],
"araClickRate": 0.6205,
"araShareRate": 0,
"goodsValue": 0.0701,
"marketPeriod": "S9,S10",
"brand": null,
"hasBrandWord": false,
"keywordCn": "孩子",
"brands": ["Majosta"],
"categories": ["Digital_Video_Download"],
"titleDensityExact": 3
}
],
"terminal": null,
"hasNextPage": null,
"guestVisited": false
}
}See Errors and rate limits for error payloads, request tracing, and rate-limit headers.