Keyword Expansion API Documentation

Use the Keyword Expansion API for Amazon keyword research. Review request parameters, response fields, and runnable examples.

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/expand

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/expand \
  --header "Content-Type: application/json" \
  --header "X-API-Key: ${ECOMMERCE_DATA_API_KEY}" \
  --data '{
  "asinList": [
    "B07Z82895W"
  ],
  "historyDate": "202507",
  "marketplace": "US",
  "page": 1,
  "size": 1,
  "queryType": 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 Expansion" 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/expand
Endpoint: POST https://ecommercedataapi.com/v1/amazon/keywords/expand
API key environment variable: ECOMMERCE_DATA_API_KEY

Example request:
{
"asinList": [
"B07Z82895W"
],
"historyDate": "202507",
"marketplace": "US",
"page": 1,
"size": 1,
"queryType": 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.

Need an API key?Create API key

Open this request in Postman

Download the preconfigured collection for this endpoint, then import it into Postman.

Download Postman config

Set the apiKey collection variable after import.Create API key

Node.js example

const response = await fetch(
  'https://ecommercedataapi.com/v1/amazon/keywords/expand',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.ECOMMERCE_DATA_API_KEY,
    },
    body: JSON.stringify({
      asinList: ['B07Z82895W'],
      historyDate: '202507',
      marketplace: 'US',
      page: 1,
      size: 1,
      queryType: 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/expand",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["ECOMMERCE_DATA_API_KEY"],
    },
    json={
        "asinList": [
            "B07Z82895W",
        ],
        "historyDate": "202507",
        "marketplace": "US",
        "page": 1,
        "size": 1,
        "queryType": 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
`amazonChoice`	Boolean	No	Amazon choice.	true
`asinList`	Array	Yes	List of Amazon Standard Identification Numbers.	["B07Z82895W"]
`excludeKeywords`	Array	No	Exclude keywords.	["phone stand"]
`historyDate`	String	No	History date. Date or timestamp value.	202201
`includeKeywords`	Array	No	Include keywords.	["phone stand"]
`marketplace`	String	Yes	Amazon marketplace code. Supported values are listed in the schema.	US
`maxAdProducts`	Integer	No	Max ad products. Maximum value.	345
`maxAvgPrice`	Number	No	Max avg price. Maximum value.	30.3
`maxBid`	Number	No	Max bid. Maximum value.	23.1
`maxCompetitors`	Integer	No	Max competitors. Maximum value.	23
`maxConversionRate`	Number	No	Max conversion rate. Maximum value. Percentage or ratio value as documented.	1.4
`maxMonopolyClickRate`	Number	No	Max monopoly click rate. Maximum value.	53.1
`maxProducts`	Integer	No	Max products. Maximum value.	90
`maxPurchaseRate`	Number	No	Max purchase rate. Maximum value. Percentage or ratio value as documented.	43
`maxPurchases`	Integer	No	Max purchases. Maximum value.	34
`maxSPR`	Integer	No	Max SPR. Maximum value.	16
`maxSearchRank`	Integer	No	Max search rank. Maximum value.	3223
`maxSearches`	Integer	No	Max searches. Maximum value.	300
`maxSupplyDemandRatio`	Number	No	Max supply demand ratio. Maximum value.	45.2
`maxTitleDensity`	Integer	No	Max title density. Maximum value.	23
`maxTrafficPercentage`	Number	No	Max traffic percentage. Maximum value. Percentage or ratio value as documented.	23
`maxWordCount`	Integer	No	Max word count. Maximum value.	4
`minAdProducts`	Integer	No	Min ad products. Minimum value.	123
`minAvgPrice`	Number	No	Min avg price. Minimum value.	20
`minBid`	Number	No	Min bid. Minimum value.	10.2
`minCompetitors`	Integer	No	Min competitors. Minimum value.	4
`minConversionRate`	Number	No	Min conversion rate. Minimum value. Percentage or ratio value as documented.	0.23
`minMonopolyClickRate`	Number	No	Min monopoly click rate. Minimum value.	23.4
`minProducts`	Integer	No	Min products. Minimum value.	10
`minPurchaseRate`	Number	No	Min purchase rate. Minimum value. Percentage or ratio value as documented.	3
`minPurchases`	Integer	No	Min purchases. Minimum value.	6
`minSPR`	Integer	No	Min SPR. Minimum value.	2
`minSearchRank`	Integer	No	Min search rank. Minimum value.	33
`minSearches`	Integer	No	Min searches. Minimum value.	100
`minSupplyDemandRatio`	Number	No	Min supply demand ratio. Minimum value.	11.2
`minTitleDensity`	Integer	No	Min title density. Minimum value.	2
`minTrafficPercentage`	Number	No	Min traffic percentage. Minimum value. Percentage or ratio value as documented.	45
`minWordCount`	Integer	No	Min word count. Minimum value.	2
`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
`queryType`	Integer	Yes	Query type. See the documented default in the example column.	2
`returnFields`	String	No	Optional comma-separated response fields. Omit it to receive the standard payload.	keyword,keywordCn,searches
`size`	Integer	No	Number of results per page.	50

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
`keyword`	String	Keyword.	N95
`keywordCn`	String	Keyword cn.	用于录音的电话支架
`searches`	Integer	Searches.	21582
`purchases`	Integer	Purchases.	1996
`purchaseRate`	Number	Purchase rate. Percentage or ratio value as documented.	0.0925
`products`	Integer	Products.	1645
`bidMin`	Number	Bid min. Minimum value.	1.34
`bidMax`	Number	Bid max. Maximum value.	3.21
`bid`	Number	Bid.	1.6
`badges`	Array	Badges.	见表1.10
`updatedTime`	Integer	Updated time. Date or timestamp value.	-
`searchesRank`	Integer	Searches rank.	25
`searchesRankTimeFrom`	Integer	Searches rank time from. Date or timestamp value.	-
`searchesRankTimeTo`	Integer	Searches rank time to.	-
`latest1daysAds`	Integer	Latest1days ads.	70
`latest7daysAds`	Integer	Latest7days ads.	100
`latest30daysAds`	Integer	Latest30days ads.	280
`supplyDemandRatio`	Number	Supply demand ratio.	3.8
`trafficPercentage`	Number	Traffic percentage. Percentage or ratio value as documented.	0.015
`calculatedWeeklySearches`	Number	Calculated weekly searches.	40
`avgPrice`	Number	Avg price.	36.14
`avgRatings`	Integer	Avg ratings.	12223
`avgRating`	Number	Avg rating.	4.5
`titleDensity`	Integer	Title density.	42.9
`spr`	Integer	SPR.	6
`monopolyClickRate`	Number	Monopoly click rate. Percentage or ratio value as documented.	0.3
`top3ClickingRate`	Number	Top3 clicking rate.	0.0813
`top3ConversionRate`	Number	Top3 conversion rate.	0.2011
`relationVariationsItems`	Array	Relation variations items.	-
`relationVariationsItems.marketplace`	String	Marketplace.	3
`relationVariationsItems.asin`	String	ASIN.	B08P6SC34B
`relationVariationsItems.imageUrl`	String	Image URL.	10
`relationVariationsItems.trafficPercentage`	Number	Traffic percentage. Percentage or ratio value as documented.	54.6
`relationVariationsItems.title`	String	Title.	-
`relationVariationsItems.price`	Number	Price.	60
`relationVariationsItems.reviews`	Number	Reviews.	10
`relationVariationsItems.rating`	Number	Rating.	4.5

Response example

{
  "request_id": "8fb43e59-4ff9-4dc8-a4b7-2ed164e45ab8",
  "data": {
    "guestId": null,
    "pages": 1026,
    "page": 1,
    "size": 1,
    "total": 1026,
    "took": 41,
    "url": null,
    "order": {
      "field": "",
      "desc": true
    },
    "items": [
      {
        "keyword": "phone stand",
        "keywordCn": "手机支架",
        "searches": 230786,
        "products": 109304,
        "purchases": 8862,
        "purchaseRate": 0.0384,
        "bid": 1.49,
        "bidMax": 1.86,
        "bidMin": 1.12,
        "badges": ["R"],
        "rankPosition": null,
        "adPosition": null,
        "updatedTime": 1753237657000,
        "searchesRank": 2096,
        "searchesRankTimeFrom": 1752940800000,
        "searchesRankTimeTo": 1753459200000,
        "latest1daysAds": 0,
        "latest7daysAds": 133,
        "latest30daysAds": 841,
        "supplyDemandRatio": 2.11,
        "trafficPercentage": 0.1131,
        "calculatedWeeklySearches": 53388.32,
        "avgPrice": 9.99,
        "avgReviews": 58501,
        "avgRating": 4.8,
        "titleDensity": 32,
        "spr": null,
        "monopolyClickRate": 0.2511,
        "top3ClickingRate": 0.2511,
        "top3ConversionRate": 0.1859,
        "relationVariationsItems": [
          {
            "marketplace": "US",
            "asin": "B07Z82895W",
            "imageUrl": "https://m.media-amazon.com/images/I/417iJirME2L._AC_SR200,200_.jpg",
            "trafficPercentage": 0.11315,
            "title": "LISEN Cell Phone Stand Adjustable for iPhone Phone Holder for Desk, Office Desk Accessories Computer PC for iPhone Stand Gaming Essentials Fit Otterbox Case Phones Switch Kindle iPad Air Tablet 4-10in",
            "price": 9.99,
            "reviews": 8360,
            "rating": 4.5
          }
        ]
      }
    ],
    "terminal": null,
    "hasNextPage": null,
    "guestVisited": false
  }
}

See Errors and rate limits for error payloads, request tracing, and rate-limit headers.

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/expand

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/expand \
  --header "Content-Type: application/json" \
  --header "X-API-Key: ${ECOMMERCE_DATA_API_KEY}" \
  --data '{
  "asinList": [
    "B07Z82895W"
  ],
  "historyDate": "202507",
  "marketplace": "US",
  "page": 1,
  "size": 1,
  "queryType": 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 Expansion" endpoint from Ecommerce Data API into the current repository. Make the changes directly instead of only returning sample code.

Example request:
{
"asinList": [
"B07Z82895W"
],
"historyDate": "202507",
"marketplace": "US",
"page": 1,
"size": 1,
"queryType": 1
}

Need an API key?Create API key

Open this request in Postman

Download the preconfigured collection for this endpoint, then import it into Postman.

Download Postman config

Set the apiKey collection variable after import.Create API key

Node.js example

const response = await fetch(
  'https://ecommercedataapi.com/v1/amazon/keywords/expand',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.ECOMMERCE_DATA_API_KEY,
    },
    body: JSON.stringify({
      asinList: ['B07Z82895W'],
      historyDate: '202507',
      marketplace: 'US',
      page: 1,
      size: 1,
      queryType: 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/expand",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["ECOMMERCE_DATA_API_KEY"],
    },
    json={
        "asinList": [
            "B07Z82895W",
        ],
        "historyDate": "202507",
        "marketplace": "US",
        "page": 1,
        "size": 1,
        "queryType": 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
`amazonChoice`	Boolean	No	Amazon choice.	true
`asinList`	Array	Yes	List of Amazon Standard Identification Numbers.	["B07Z82895W"]
`excludeKeywords`	Array	No	Exclude keywords.	["phone stand"]
`historyDate`	String	No	History date. Date or timestamp value.	202201
`includeKeywords`	Array	No	Include keywords.	["phone stand"]
`marketplace`	String	Yes	Amazon marketplace code. Supported values are listed in the schema.	US
`maxAdProducts`	Integer	No	Max ad products. Maximum value.	345
`maxAvgPrice`	Number	No	Max avg price. Maximum value.	30.3
`maxBid`	Number	No	Max bid. Maximum value.	23.1
`maxCompetitors`	Integer	No	Max competitors. Maximum value.	23
`maxConversionRate`	Number	No	Max conversion rate. Maximum value. Percentage or ratio value as documented.	1.4
`maxMonopolyClickRate`	Number	No	Max monopoly click rate. Maximum value.	53.1
`maxProducts`	Integer	No	Max products. Maximum value.	90
`maxPurchaseRate`	Number	No	Max purchase rate. Maximum value. Percentage or ratio value as documented.	43
`maxPurchases`	Integer	No	Max purchases. Maximum value.	34
`maxSPR`	Integer	No	Max SPR. Maximum value.	16
`maxSearchRank`	Integer	No	Max search rank. Maximum value.	3223
`maxSearches`	Integer	No	Max searches. Maximum value.	300
`maxSupplyDemandRatio`	Number	No	Max supply demand ratio. Maximum value.	45.2
`maxTitleDensity`	Integer	No	Max title density. Maximum value.	23
`maxTrafficPercentage`	Number	No	Max traffic percentage. Maximum value. Percentage or ratio value as documented.	23
`maxWordCount`	Integer	No	Max word count. Maximum value.	4
`minAdProducts`	Integer	No	Min ad products. Minimum value.	123
`minAvgPrice`	Number	No	Min avg price. Minimum value.	20
`minBid`	Number	No	Min bid. Minimum value.	10.2
`minCompetitors`	Integer	No	Min competitors. Minimum value.	4
`minConversionRate`	Number	No	Min conversion rate. Minimum value. Percentage or ratio value as documented.	0.23
`minMonopolyClickRate`	Number	No	Min monopoly click rate. Minimum value.	23.4
`minProducts`	Integer	No	Min products. Minimum value.	10
`minPurchaseRate`	Number	No	Min purchase rate. Minimum value. Percentage or ratio value as documented.	3
`minPurchases`	Integer	No	Min purchases. Minimum value.	6
`minSPR`	Integer	No	Min SPR. Minimum value.	2
`minSearchRank`	Integer	No	Min search rank. Minimum value.	33
`minSearches`	Integer	No	Min searches. Minimum value.	100
`minSupplyDemandRatio`	Number	No	Min supply demand ratio. Minimum value.	11.2
`minTitleDensity`	Integer	No	Min title density. Minimum value.	2
`minTrafficPercentage`	Number	No	Min traffic percentage. Minimum value. Percentage or ratio value as documented.	45
`minWordCount`	Integer	No	Min word count. Minimum value.	2
`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
`queryType`	Integer	Yes	Query type. See the documented default in the example column.	2
`returnFields`	String	No	Optional comma-separated response fields. Omit it to receive the standard payload.	keyword,keywordCn,searches
`size`	Integer	No	Number of results per page.	50

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
`keyword`	String	Keyword.	N95
`keywordCn`	String	Keyword cn.	用于录音的电话支架
`searches`	Integer	Searches.	21582
`purchases`	Integer	Purchases.	1996
`purchaseRate`	Number	Purchase rate. Percentage or ratio value as documented.	0.0925
`products`	Integer	Products.	1645
`bidMin`	Number	Bid min. Minimum value.	1.34
`bidMax`	Number	Bid max. Maximum value.	3.21
`bid`	Number	Bid.	1.6
`badges`	Array	Badges.	见表1.10
`updatedTime`	Integer	Updated time. Date or timestamp value.	-
`searchesRank`	Integer	Searches rank.	25
`searchesRankTimeFrom`	Integer	Searches rank time from. Date or timestamp value.	-
`searchesRankTimeTo`	Integer	Searches rank time to.	-
`latest1daysAds`	Integer	Latest1days ads.	70
`latest7daysAds`	Integer	Latest7days ads.	100
`latest30daysAds`	Integer	Latest30days ads.	280
`supplyDemandRatio`	Number	Supply demand ratio.	3.8
`trafficPercentage`	Number	Traffic percentage. Percentage or ratio value as documented.	0.015
`calculatedWeeklySearches`	Number	Calculated weekly searches.	40
`avgPrice`	Number	Avg price.	36.14
`avgRatings`	Integer	Avg ratings.	12223
`avgRating`	Number	Avg rating.	4.5
`titleDensity`	Integer	Title density.	42.9
`spr`	Integer	SPR.	6
`monopolyClickRate`	Number	Monopoly click rate. Percentage or ratio value as documented.	0.3
`top3ClickingRate`	Number	Top3 clicking rate.	0.0813
`top3ConversionRate`	Number	Top3 conversion rate.	0.2011
`relationVariationsItems`	Array	Relation variations items.	-
`relationVariationsItems.marketplace`	String	Marketplace.	3
`relationVariationsItems.asin`	String	ASIN.	B08P6SC34B
`relationVariationsItems.imageUrl`	String	Image URL.	10
`relationVariationsItems.trafficPercentage`	Number	Traffic percentage. Percentage or ratio value as documented.	54.6
`relationVariationsItems.title`	String	Title.	-
`relationVariationsItems.price`	Number	Price.	60
`relationVariationsItems.reviews`	Number	Reviews.	10
`relationVariationsItems.rating`	Number	Rating.	4.5

Response example

{
  "request_id": "8fb43e59-4ff9-4dc8-a4b7-2ed164e45ab8",
  "data": {
    "guestId": null,
    "pages": 1026,
    "page": 1,
    "size": 1,
    "total": 1026,
    "took": 41,
    "url": null,
    "order": {
      "field": "",
      "desc": true
    },
    "items": [
      {
        "keyword": "phone stand",
        "keywordCn": "手机支架",
        "searches": 230786,
        "products": 109304,
        "purchases": 8862,
        "purchaseRate": 0.0384,
        "bid": 1.49,
        "bidMax": 1.86,
        "bidMin": 1.12,
        "badges": ["R"],
        "rankPosition": null,
        "adPosition": null,
        "updatedTime": 1753237657000,
        "searchesRank": 2096,
        "searchesRankTimeFrom": 1752940800000,
        "searchesRankTimeTo": 1753459200000,
        "latest1daysAds": 0,
        "latest7daysAds": 133,
        "latest30daysAds": 841,
        "supplyDemandRatio": 2.11,
        "trafficPercentage": 0.1131,
        "calculatedWeeklySearches": 53388.32,
        "avgPrice": 9.99,
        "avgReviews": 58501,
        "avgRating": 4.8,
        "titleDensity": 32,
        "spr": null,
        "monopolyClickRate": 0.2511,
        "top3ClickingRate": 0.2511,
        "top3ConversionRate": 0.1859,
        "relationVariationsItems": [
          {
            "marketplace": "US",
            "asin": "B07Z82895W",
            "imageUrl": "https://m.media-amazon.com/images/I/417iJirME2L._AC_SR200,200_.jpg",
            "trafficPercentage": 0.11315,
            "title": "LISEN Cell Phone Stand Adjustable for iPhone Phone Holder for Desk, Office Desk Accessories Computer PC for iPhone Stand Gaming Essentials Fit Otterbox Case Phones Switch Kindle iPad Air Tablet 4-10in",
            "price": 9.99,
            "reviews": 8360,
            "rating": 4.5
          }
        ]
      }
    ],
    "terminal": null,
    "hasNextPage": null,
    "guestVisited": false
  }
}

See Errors and rate limits for error payloads, request tracing, and rate-limit headers.

Keyword Expansion

API data samples

Quick call

Integrate with an AI CLI

Copy for your AI CLI

Open this request in Postman

Node.js example

Python example

Request body

Response structure

Response fields

Response example

On this page

Keyword Expansion

API data samples

Quick call

Integrate with an AI CLI

Copy for your AI CLI

Open this request in Postman

Node.js example

Python example

Request body

Response structure

Response fields

Response example

On this page