Keyword Conversion API Documentation

Use the Keyword Conversion 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/keyword/conversion

The request and response fields below match the current public contract.

API mapping

Item	Value
MCP Code	`keyword_conversion`
Original REST method	`POST`
Original REST path	`/v1/keyword/conversion`
Original API documentation	Open the official API documentation

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/keyword/conversion \
  --header "Content-Type: application/json" \
  --header "X-API-Key: ${ECOMMERCE_DATA_API_KEY}" \
  --data '{
  "marketplace": "US",
  "keyword": "lunch box",
  "timeType": "WEEK",
  "minSearches": 100,
  "maxSearches": 100000
}'

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 Conversion" 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/keyword/conversion
Endpoint: POST https://ecommercedataapi.com/v1/amazon/keyword/conversion
API key environment variable: ECOMMERCE_DATA_API_KEY

Example request:
{
"marketplace": "US",
"keyword": "lunch box",
"timeType": "WEEK",
"minSearches": 100,
"maxSearches": 100000
}

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/keyword/conversion',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.ECOMMERCE_DATA_API_KEY,
    },
    body: JSON.stringify({
      marketplace: 'US',
      keyword: 'lunch box',
      timeType: 'WEEK',
      minSearches: 100,
      maxSearches: 100000,
    }),
  }
);

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/keyword/conversion",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["ECOMMERCE_DATA_API_KEY"],
    },
    json={
        "marketplace": "US",
        "keyword": "lunch box",
        "timeType": "WEEK",
        "minSearches": 100,
        "maxSearches": 100000,
    },
    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
`marketplace`	String	Yes	Amazon marketplace code. Supported values are listed in the schema.	US
`keyword`	String	Yes	Keyword used by the query.	wireless charger
`timeType`	String	No	Time type. Date or timestamp value.	WEEK: 按周；90D：近90天
`minSearches`	Integer	No	Min searches. Minimum value.	1
`maxSearches`	Integer	No	Max searches. Maximum value.	1
`minClicks`	Integer	No	Min clicks. Minimum value.	1
`maxClicks`	Integer	No	Max clicks. Maximum value.	1
`minPurchases`	Integer	No	Min purchases. Minimum value.	1
`maxPurchases`	Integer	No	Max purchases. Maximum value.	1
`minSearchConvRate`	Number	No	Min search conv rate. Minimum value. Percentage or ratio value as documented.	1
`maxSearchConvRate`	Number	No	Max search conv rate. Maximum value. Percentage or ratio value as documented.	1
`minClickConvRate`	Number	No	Min click conv rate. Minimum value. Percentage or ratio value as documented.	1
`maxClickConvRate`	Number	No	Max click conv rate. Maximum value. Percentage or ratio value as documented.	1
`minPpc`	Number	No	Min PPC. Minimum value.	1
`maxPpc`	Number	No	Max PPC. Maximum value.	1
`minCpa`	Number	No	Min cpa. Minimum value.	1
`maxCpa`	Number	No	Max cpa. Maximum value.	1
`minProductPrice`	Number	No	Min product price. Minimum value.	1
`maxProductPrice`	Number	No	Max product price. Maximum value.	1
`minAcos`	Number	No	Min acos. Minimum value.	1
`maxAcos`	Number	No	Max acos. Maximum value.	1
`minClickingRate`	Number	No	Min clicking rate. Minimum value. Percentage or ratio value as documented.	1
`maxClickingRate`	Number	No	Max clicking rate. Maximum value. Percentage or ratio value as documented.	1
`minConversionRate`	Number	No	Min conversion rate. Minimum value. Percentage or ratio value as documented.	1
`maxConversionRate`	Number	No	Max conversion rate. Maximum value. Percentage or ratio value as documented.	1
`minPhraseCount`	Integer	No	Min phrase count. Minimum value.	1
`maxPhraseCount`	Integer	No	Max phrase count. Maximum value.	1
`minBudget`	Number	No	Min budget. Minimum value.	1
`maxBudget`	Number	No	Max budget. Maximum value.	1
`matchType`	Integer	No	Match type.	1
`includeKeywords`	Array	No	Include keywords.	["Include keywords"]
`excludeKeywords`	Array	No	Exclude keywords.	["Exclude keywords"]
`customAvgProductPrice`	Number	No	Custom avg product price.	1

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.	-
`keywordCn`	String	Keyword cn.	-
`keywordJp`	String	Keyword jp.	-
`searches`	Integer	Searches.	-
`clicks`	Integer	Clicks.	-
`purchases`	Integer	Purchases.	-
`searchConvRate`	Number	Search conv rate. Percentage or ratio value as documented.	-
`clickConvRate`	Number	Click conv rate. Percentage or ratio value as documented.	-
`searchesTrend`	String	Searches trend.	-
`clickTrend`	String	Click trend.	-
`purchaseTrend`	String	Purchase trend.	-
`clickingRate`	Number	Clicking rate. Percentage or ratio value as documented.	-
`conversionRate`	Number	Conversion rate. Percentage or ratio value as documented.	-
`phraseCount`	Integer	Phrase count.	-
`phrasePpc`	String	Phrase PPC.	-
`phrasePpc.min`	Number	Min. Minimum value.	-
`phrasePpc.max`	Number	Max. Maximum value.	-
`phrasePpc.value`	Number	Value.	-
`exactPpc`	String	Exact PPC.	-
`exactPpc.min`	Number	Min. Minimum value.	-
`exactPpc.max`	Number	Max. Maximum value.	-
`exactPpc.value`	Number	Value.	-
`broadPpc`	String	Broad PPC.	-
`broadPpc.min`	Number	Min. Minimum value.	-
`broadPpc.max`	Number	Max. Maximum value.	-
`broadPpc.value`	Number	Value.	-
`phraseCpa`	String	Phrase cpa.	-
`phraseCpa.min`	Number	Min. Minimum value.	-
`phraseCpa.max`	Number	Max. Maximum value.	-
`phraseCpa.value`	Number	Value.	-
`exactCpa`	String	Exact cpa.	-
`exactCpa.min`	Number	Min. Minimum value.	-
`exactCpa.max`	Number	Max. Maximum value.	-
`exactCpa.value`	Number	Value.	-
`broadCpa`	String	Broad cpa.	-
`broadCpa.min`	Number	Min. Minimum value.	-
`broadCpa.max`	Number	Max. Maximum value.	-
`broadCpa.value`	Number	Value.	-
`phraseBudget`	String	Phrase budget.	-
`phraseBudget.min`	Number	Min. Minimum value.	-
`phraseBudget.max`	Number	Max. Maximum value.	-
`phraseBudget.value`	Number	Value.	-
`exactBudget`	String	Exact budget.	-
`exactBudget.min`	Number	Min. Minimum value.	-
`exactBudget.max`	Number	Max. Maximum value.	-
`exactBudget.value`	Number	Value.	-
`broadBudget`	String	Broad budget.	-
`broadBudget.min`	Number	Min. Minimum value.	-
`broadBudget.max`	Number	Max. Maximum value.	-
`broadBudget.value`	Number	Value.	-
`phraseAcos`	String	Phrase acos.	-
`phraseAcos.min`	Number	Min. Minimum value.	-
`phraseAcos.max`	Number	Max. Maximum value.	-
`phraseAcos.value`	Number	Value.	-
`exactAcos`	String	Exact acos.	-
`exactAcos.min`	Number	Min. Minimum value.	-
`exactAcos.max`	Number	Max. Maximum value.	-
`exactAcos.value`	Number	Value.	-
`broadAcos`	String	Broad acos.	-
`broadAcos.min`	Number	Min. Minimum value.	-
`broadAcos.max`	Number	Max. Maximum value.	-
`broadAcos.value`	Number	Value.	-
`avgProductPrice`	String	Avg product price.	-
`avgProductPrice.min`	Number	Min. Minimum value.	-
`avgProductPrice.max`	Number	Max. Maximum value.	-
`avgProductPrice.value`	Number	Value.	-
`top3Asins`	Array	Top3 asins.	-
`top10Asins`	Array	Top10 asins.	-

Response example

{
  "request_id": "8fb43e59-4ff9-4dc8-a4b7-2ed164e45ab8",
  "data": {
    "guestId": null,
    "pages": 0,
    "page": 1,
    "size": 2,
    "total": 2394,
    "took": 0,
    "url": null,
    "order": {
      "field": "",
      "desc": true
    },
    "items": [
      {
        "keyword": "lunch box",
        "keywordCn": "午餐盒",
        "keywordJp": "弁当箱",
        "searches": 349991,
        "clicks": 91282,
        "purchases": 5412,
        "searchConvRate": 0.0155,
        "clickConvRate": 0.0593,
        "searchesTrend": null,
        "clickTrend": null,
        "purchaseTrend": null,
        "phrasePpc": {
          "value": 0.7,
          "min": 0.49,
          "max": 0.79
        },
        "exactPpc": {
          "value": 0.58,
          "min": 0.45,
          "max": 0.65
        },
        "broadPpc": {
          "value": 0.71,
          "min": 0.49,
          "max": 0.79
        },
        "phraseCpa": {
          "value": 11.8044,
          "min": 8.2631,
          "max": 13.3221
        },
        "exactCpa": {
          "value": 9.7808,
          "min": 7.5885,
          "max": 10.9612
        },
        "broadCpa": {
          "value": 11.973,
          "min": 8.2631,
          "max": 13.3221
        },
        "avgProductPrice": {
          "value": 22.99,
          "min": 6.99,
          "max": 66.99
        },
        "phraseBudget": {
          "value": 18.9,
          "min": 13.23,
          "max": 21.33
        },
        "exactBudget": {
          "value": 15.66,
          "min": 12.15,
          "max": 17.55
        },
        "broadBudget": {
          "value": 19.17,
          "min": 13.23,
          "max": 21.33
        },
        "phraseAcos": {
          "value": 0.5135,
          "min": 1.6888,
          "max": 0.1762
        },
        "exactAcos": {
          "value": 0.4254,
          "min": 1.3993,
          "max": 0.146
        },
        "broadAcos": {
          "value": 0.5208,
          "min": 1.7129,
          "max": 0.1787
        },
        "clickingRate": 0.1976,
        "conversionRate": 0.1329,
        "top3Asins": [
          {
            "asin": "B0GDZLL8BK",
            "imageUrl": "https://m.media-amazon.com/images/I/41p2Jl7uYAL._AC_US200_.jpg",
            "clickRate": 0.0912,
            "conversionRate": 0.0271
          }
        ],
        "top10Asins": [
          {
            "station": "US",
            "keyword": "lunch box",
            "categoryId": null,
            "maxPage": null,
            "asin": "B0DBDKT4QC",
            "asinUrl": "HOTOR Insulated Lunch Box for Men & Women - Leak-Proof Cooler Lunch Bag with 4 Pockets, Adjustable Strap, Ideal for Work, Picnic, Travel - Medium, Black, 10.2\"×6.9\"×8.5\"",
            "asinImage": "https://m.media-amazon.com/images/I/41w24kLyRVL._AC_US200_.jpg",
            "bigAsinImage": null,
            "asinPrice": 8.99,
            "asinReviews": 7423,
            "asinRating": 4.5,
            "asinBrand": null,
            "asinTitle": "HOTOR Insulated Lunch Box for Men & Women - Leak-Proof Cooler Lunch Bag with 4 Pockets, Adjustable Strap, Ideal for Work, Picnic, Travel - Medium, Black, 10.2\"×6.9\"×8.5\"",
            "rank": null,
            "rankPage": 1,
            "rankPagesize": 56,
            "rankIndex": 4,
            "position": 4,
            "products": 30639,
            "sku": null,
            "maxRankPage": null,
            "ad": null,
            "amazonChoice": null,
            "badges": "AC",
            "handledImageUrl": true
          }
        ],
        "phraseCount": 2
      }
    ],
    "terminal": null,
    "hasNextPage": null,
    "guestVisited": false
  }
}

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

AI skills and agents that use this API

Start from a seller task, see how these capabilities use the current API, and review source and permissions before installation.

Amazon Advertising Strategy

Plan Sponsored Products, Sponsored Brands, Sponsored Display, budget allocation, ACoS optimization, and performance review.

Amazon Brand Analytics

Interpret search frequency, market basket, item comparison, and demographic evidence for Amazon brand decisions.

Amazon Negative Keywords

Analyze Amazon search terms, identify waste, estimate savings, and propose negative keyword rules with review safeguards.

Amazon PPC Campaign Builder

Build or audit Amazon PPC structures, keyword groups, bids, negatives, ACoS targets, and week-by-week optimization actions.

Browse the complete AI Hub