Market Research API Documentation

Use the Market Research API for Amazon market analysis. 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/markets/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/markets/research \
  --header "Content-Type: application/json" \
  --header "X-API-Key: ${ECOMMERCE_DATA_API_KEY}" \
  --data '{
  "marketplace": "US",
  "month": "202507",
  "nodeIdPath": "172282:281407",
  "minAvgUnits": 100,
  "maxAvgUnits": 10000,
  "page": 1,
  "size": 20,
  "order": {
    "field": "avgUnits",
    "desc": true
  }
}'

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

Example request:
{
"marketplace": "US",
"month": "202507",
"nodeIdPath": "172282:281407",
"minAvgUnits": 100,
"maxAvgUnits": 10000,
"page": 1,
"size": 20,
"order": {
"field": "avgUnits",
"desc": true
}
}

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/markets/research',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.ECOMMERCE_DATA_API_KEY,
    },
    body: JSON.stringify({
      marketplace: 'US',
      month: '202507',
      nodeIdPath: '172282:281407',
      minAvgUnits: 100,
      maxAvgUnits: 10000,
      page: 1,
      size: 20,
      order: {
        field: 'avgUnits',
        desc: true,
      },
    }),
  }
);

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/markets/research",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["ECOMMERCE_DATA_API_KEY"],
    },
    json={
        "marketplace": "US",
        "month": "202507",
        "nodeIdPath": "172282:281407",
        "minAvgUnits": 100,
        "maxAvgUnits": 10000,
        "page": 1,
        "size": 20,
        "order": {
            "field": "avgUnits",
            "desc": True,
        },
    },
    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
`departmentKeyword`	String	No	Department keyword.	Electronics:Accessories & Supplies
`marketplace`	String	Yes	Amazon marketplace code. Supported values are listed in the schema.	US
`maxAmazonSelfProportion`	Number	No	Max Amazon self proportion. Maximum value. Percentage or ratio value as documented.	56
`maxAvgBsr`	Integer	No	Max avg BSR. Maximum value.	100
`maxAvgPrice`	Number	No	Max avg price. Maximum value.	50
`maxAvgProfit`	Number	No	Max avg profit. Maximum value. Percentage or ratio value as documented.	70
`maxAvgRating`	Number	No	Max avg rating. Maximum value.	3
`maxAvgRatings`	Integer	No	Max avg ratings. Maximum value.	500
`maxAvgRevenue`	Number	No	Max avg revenue. Maximum value.	900
`maxAvgSellers`	Number	No	Max avg sellers. Maximum value.	10.4
`maxAvgUnits`	Integer	No	Max avg units. Maximum value.	10000
`maxBrandCrn`	Number	No	Max brand crn. Maximum value.	55
`maxBrands`	Integer	No	Max brands. Maximum value.	20
`maxEbcProportion`	Number	No	Max A+ content proportion. Maximum value. Percentage or ratio value as documented.	54
`maxFbaProportion`	Number	No	Max FBA proportion. Maximum value. Percentage or ratio value as documented.	54
`maxFbmProportion`	Number	No	Max FBM proportion. Maximum value. Percentage or ratio value as documented.	54
`maxGoodsCount`	Integer	No	Max goods count. Maximum value.	90
`maxGoodsCrn`	Number	No	Max goods crn. Maximum value.	55
`maxNewAvgPrice`	Number	No	Max new avg price. Maximum value.	45
`maxNewAvgRating`	Number	No	Max new avg rating. Maximum value.	4.5
`maxNewAvgRatings`	Integer	No	Max new avg ratings. Maximum value.	554
`maxNewAvgRevenue`	Number	No	Max new avg revenue. Maximum value.	2000
`maxNewAvgUnits`	Number	No	Max new avg units. Maximum value.	800
`maxNewCount`	Integer	No	Max new count. Maximum value.	20
`maxNewProportion`	Number	No	Max new proportion. Maximum value. Percentage or ratio value as documented.	56
`maxSellerCrn`	Number	No	Max seller crn. Maximum value.	45
`maxSellers`	Integer	No	Max sellers. Maximum value.	10
`maxTopAvgBsr`	Integer	No	Max top avg BSR. Maximum value.	998
`maxTopAvgRevenue`	Number	No	Max top avg revenue. Maximum value.	3000
`maxTopAvgUnits`	Integer	No	Max top avg units. Maximum value.	300
`maxVolume`	Number	No	Max volume. Maximum value.	50
`maxWeight`	Number	No	Max weight. Maximum value.	60
`minAmazonSelfProportion`	Number	No	Min Amazon self proportion. Minimum value. Percentage or ratio value as documented.	34
`minAvgBsr`	Integer	No	Min avg BSR. Minimum value.	50
`minAvgPrice`	Number	No	Min avg price. Minimum value.	30
`minAvgProfit`	Number	No	Min avg profit. Minimum value. Percentage or ratio value as documented.	20
`minAvgRating`	Number	No	Min avg rating. Minimum value.	2.5
`minAvgRatings`	Integer	No	Min avg ratings. Minimum value.	100
`minAvgRevenue`	Number	No	Min avg revenue. Minimum value.	100
`minAvgSellers`	Number	No	Min avg sellers. Minimum value.	4.4
`minAvgUnits`	Integer	No	Min avg units. Minimum value.	100
`minBrandCrn`	Number	No	Min brand crn. Minimum value.	45
`minBrands`	Integer	No	Min brands. Minimum value.	10
`minEbcProportion`	Number	No	Min A+ content proportion. Minimum value. Percentage or ratio value as documented.	34
`minFbaProportion`	Number	No	Min FBA proportion. Minimum value. Percentage or ratio value as documented.	34
`minFbmProportion`	Number	No	Min FBM proportion. Minimum value. Percentage or ratio value as documented.	34
`minGoodsCount`	Integer	No	Min goods count. Minimum value.	40
`minGoodsCrn`	Number	No	Min goods crn. Minimum value.	45
`minNewAvgPrice`	Number	No	Min new avg price. Minimum value.	34
`minNewAvgRating`	Number	No	Min new avg rating. Minimum value.	4
`minNewAvgRatings`	Integer	No	Min new avg ratings. Minimum value.	23
`minNewAvgRevenue`	Number	No	Min new avg revenue. Minimum value.	900
`minNewAvgUnits`	Number	No	Min new avg units. Minimum value.	400
`minNewCount`	Integer	No	Min new count. Minimum value.	4
`minNewProportion`	Number	No	Min new proportion. Minimum value. Percentage or ratio value as documented.	34
`minSellerCrn`	Number	No	Min seller crn. Minimum value.	55
`minSellers`	Integer	No	Min sellers. Minimum value.	6
`minTopAvgBsr`	Integer	No	Min top avg BSR. Minimum value.	68
`minTopAvgRevenue`	Number	No	Min top avg revenue. Minimum value.	2000
`minTopAvgUnits`	Integer	No	Min top avg units. Minimum value.	200
`minVolume`	Number	No	Min volume. Minimum value.	20
`minWeight`	Number	No	Min weight. Minimum value.	30
`month`	String	No	Data month. Use the format documented for this endpoint, usually yyyyMM.	202507
`newProduct`	Integer	No	New product. See the documented default in the example column.	3
`nodeIdPath`	String	No	Amazon category node path.	172282:281407
`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,currency,nodeId
`sellerLocation`	String	No	Seller location.	US,GB
`size`	Integer	No	Number of results per page.	50
`topNum`	Integer	No	Top num.	10

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
`currency`	String	Currency.	USD
`nodeId`	String	Node ID.	3732981
`nodeLabelName`	String	Node label name.	Mattresses
`nodeIdPath`	String	Node ID path.	1055398:1063306:1063308:3732961:3732981
`nodeLabelPath`	String	Node label path.	Home & Kitchen:Furniture:Bedroom Furniture:Mattresses & Box Springs:Mattresses
`nodeLabelLocale`	String	Node label locale.	床垫
`nodeLabelPathLocale`	String	Node label path locale.	家居用品厨房:家具:家具卧室:床垫:床垫
`totalProducts`	Integer	Total products.	1000
`ranking`	Integer	Ranking.	1
`topProducts`	Integer	Top products.	100
`brands`	Integer	Brands.	34
`sellers`	Integer	Sellers.	60
`totalUnits`	Integer	Total units.	539009
`totalRevenue`	Number	Total revenue.	179950610.4
`avgUnits`	Integer	Avg units.	5390
`avgRevenue`	Number	Avg revenue.	1799506
`avgPrice`	Number	Avg price.	296.11
`avgRatings`	Integer	Avg ratings.	14591
`avgRating`	Number	Avg rating.	4.5
`avgBsr`	Integer	Avg BSR.	198077
`baseAvgVolume`	Number	Base avg volume.	529430.46
`avgVolume`	Number	Avg volume.	32307.87
`baseAvgWeight`	Number	Base avg weight.	35301.19
`avgWeight`	Number	Avg weight.	77.8259
`avgProfit`	Number	Avg profit. Percentage or ratio value as documented.	68.76
`avgSellers`	Number	Avg sellers.	3.3
`ebcProportion`	Number	A+ content proportion. Percentage or ratio value as documented.	80
`amazonSelfProportion`	Number	Amazon self proportion. Percentage or ratio value as documented.	55
`fbaProportion`	Number	FBA proportion. Percentage or ratio value as documented.	22
`fbmProportion`	Number	FBM proportion. Percentage or ratio value as documented.	14
`sellerNation`	String	Seller nation.	US
`sellerNationLabel`	String	Seller nation label.	美国
`sellerProportion`	Number	Seller proportion. Percentage or ratio value as documented.	59.3
`top10Images`	Array	Top10 images.	-
`top10Images.asin`	String	ASIN.	B01IU6RJYA
`top10Images.image`	String	Image.	https://images-na.ssl-images-amazon.com/images/I/51+5VVLcXSL._AC_US200_.jpg
`returnRatio`	Number	Return ratio. Percentage or ratio value as documented.	3.51
`avgReturnRatio`	Number	Avg return ratio. Percentage or ratio value as documented.	5.54
`searchToPurchaseRatio`	Number	Search to purchase ratio.	0.94926
`top3ProductSales`	Integer	Top3 product sales.	-
`top3BrandSales`	Integer	Top3 brand sales.	-
`top3SellerSales`	Integer	Top3 seller sales.	-
`top3ProductRevenue`	Number	Top3 product revenue.	-
`top3BrandRevenue`	Number	Top3 brand revenue.	-
`top3SellerRevenue`	Number	Top3 seller revenue.	-
`top3ProductCrn`	Number	Top3 product crn.	-
`top3BrandCrn`	Number	Top3 brand crn.	-
`top3SellerCrn`	Number	Top3 seller crn.	-
`top5ProductSales`	Integer	Top5 product sales.	-
`top5BrandSales`	Integer	Top5 brand sales.	-
`top5SellerSales`	Integer	Top5 seller sales.	-
`top5ProductRevenue`	Number	Top5 product revenue.	-
`top5BrandRevenue`	Number	Top5 brand revenue.	-
`top5SellerRevenue`	Number	Top5 seller revenue.	-
`top5ProductCrn`	Number	Top5 product crn.	-
`top5BrandCrn`	Number	Top5 brand crn.	-
`top5SellerCrn`	Number	Top5 seller crn.	-
`top10ProductSales`	Integer	Top10 product sales.	-
`top10BrandSales`	Integer	Top10 brand sales.	-
`top10SellerSales`	Integer	Top10 seller sales.	-
`top10ProductRevenue`	Number	Top10 product revenue.	-
`top10BrandRevenue`	Number	Top10 brand revenue.	-
`top10SellerRevenue`	Number	Top10 seller revenue.	-
`top10ProductCrn`	Number	Top10 product crn.	-
`top10BrandCrn`	Number	Top10 brand crn.	-
`top10SellerCrn`	Number	Top10 seller crn.	-
`top20ProductSales`	Integer	Top20 product sales.	-
`top20BrandSales`	Integer	Top20 brand sales.	-
`top20SellerSales`	Integer	Top20 seller sales.	-
`top20ProductRevenue`	Number	Top20 product revenue.	-
`top20BrandRevenue`	Number	Top20 brand revenue.	-
`top20SellerRevenue`	Number	Top20 seller revenue.	-
`top20ProductCrn`	Number	Top20 product crn.	-
`top20BrandCrn`	Number	Top20 brand crn.	-
`top20SellerCrn`	Number	Top20 seller crn.	-
`l1NewRatio`	Number	L1 new ratio. Percentage or ratio value as documented.	-
`l1NewCount`	Integer	L1 new count.	-
`l1NewAvgPrice`	Number	L1 new avg price.	-
`l1NewAvgReviews`	Integer	L1 new avg reviews.	-
`l1NewAvgRating`	Number	L1 new avg rating.	-
`l1NewAvgSales`	Integer	L1 new avg sales.	-
`l1NewAvgRevenue`	Number	L1 new avg revenue.	-
`l3NewRatio`	Number	L3 new ratio. Percentage or ratio value as documented.	-
`l3NewCount`	Integer	L3 new count.	-
`l3NewAvgPrice`	Number	L3 new avg price.	-
`l3NewAvgReviews`	Integer	L3 new avg reviews.	-
`l3NewAvgRating`	Number	L3 new avg rating.	-
`l3NewAvgSales`	Integer	L3 new avg sales.	-
`l3NewAvgRevenue`	Number	L3 new avg revenue.	-
`l6NewRatio`	Number	L6 new ratio. Percentage or ratio value as documented.	-
`l6NewCount`	Integer	L6 new count.	-
`l6NewAvgPrice`	Number	L6 new avg price.	-
`l6NewAvgReviews`	Integer	L6 new avg reviews.	-
`l6NewAvgRating`	Number	L6 new avg rating.	-
`l6NewAvgSales`	Integer	L6 new avg sales.	-
`l6NewAvgRevenue`	Number	L6 new avg revenue.	-
`l12NewRatio`	Number	L12 new ratio. Percentage or ratio value as documented.	-
`l12NewCount`	Integer	L12 new count.	-
`l12NewAvgPrice`	Number	L12 new avg price.	-
`l12NewAvgReviews`	Integer	L12 new avg reviews.	-
`l12NewAvgRating`	Number	L12 new avg rating.	-
`l12NewAvgSales`	Integer	L12 new avg sales.	-
`l12NewAvgRevenue`	Number	L12 new avg revenue.	-

Response example

{
  "request_id": "8fb43e59-4ff9-4dc8-a4b7-2ed164e45ab8",
  "data": {
    "guestId": null,
    "pages": 40,
    "page": 1,
    "size": 1,
    "total": 40,
    "took": 0,
    "url": null,
    "order": {
      "field": "",
      "desc": true
    },
    "items": [
      {
        "marketplace": "US",
        "currency": "USD",
        "nodeId": 10967801,
        "nodeLabelName": "Power Strips",
        "nodeIdPath": "172282:281407:17854127011:10967801",
        "nodeLabelPath": "Electronics:Accessories & Supplies:Power Strips & Surge Protectors:Power Strips",
        "nodeLabelLocale": "剥线器",
        "nodeLabelPathLocale": "电子产品:辅料:剥线器:剥线器",
        "top10Images": [
          {
            "asin": "B09PDLBFKY",
            "image": "https://images-na.ssl-images-amazon.com/images/I/61NGPmmMAIL._AC_US200_.jpg"
          }
        ],
        "totalProducts": 2815,
        "ranking": 1,
        "topProducts": 100,
        "brands": 45,
        "sellers": 45,
        "totalUnits": 1487414,
        "totalRevenue": 22973201.92,
        "avgUnits": 14874,
        "avgRevenue": 229732,
        "avgPrice": 17.83,
        "avgRatings": 10756,
        "avgRating": 4.7,
        "avgBsr": 447,
        "baseAvgVolume": 462.27,
        "avgVolume": 28.21,
        "baseAvgWeight": 412.99,
        "avgWeight": 0.9105,
        "avgProfit": 60.3,
        "avgSellers": 1.6,
        "ebcProportion": 91,
        "amazonSelfProportion": 3,
        "fbaProportion": 96,
        "fbmProportion": 0,
        "sellerNation": "CN",
        "sellerNationLabel": "中国",
        "sellerProportion": 86,
        "returnRatio": 2.8739,
        "avgReturnRatio": 2.8656,
        "searchToPurchaseRatio": 17.91785
      }
    ],
    "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/markets/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/markets/research \
  --header "Content-Type: application/json" \
  --header "X-API-Key: ${ECOMMERCE_DATA_API_KEY}" \
  --data '{
  "marketplace": "US",
  "month": "202507",
  "nodeIdPath": "172282:281407",
  "minAvgUnits": 100,
  "maxAvgUnits": 10000,
  "page": 1,
  "size": 20,
  "order": {
    "field": "avgUnits",
    "desc": true
  }
}'

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 "Market Research" endpoint from Ecommerce Data API into the current repository. Make the changes directly instead of only returning sample code.

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/markets/research',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.ECOMMERCE_DATA_API_KEY,
    },
    body: JSON.stringify({
      marketplace: 'US',
      month: '202507',
      nodeIdPath: '172282:281407',
      minAvgUnits: 100,
      maxAvgUnits: 10000,
      page: 1,
      size: 20,
      order: {
        field: 'avgUnits',
        desc: true,
      },
    }),
  }
);

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/markets/research",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["ECOMMERCE_DATA_API_KEY"],
    },
    json={
        "marketplace": "US",
        "month": "202507",
        "nodeIdPath": "172282:281407",
        "minAvgUnits": 100,
        "maxAvgUnits": 10000,
        "page": 1,
        "size": 20,
        "order": {
            "field": "avgUnits",
            "desc": True,
        },
    },
    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
`departmentKeyword`	String	No	Department keyword.	Electronics:Accessories & Supplies
`marketplace`	String	Yes	Amazon marketplace code. Supported values are listed in the schema.	US
`maxAmazonSelfProportion`	Number	No	Max Amazon self proportion. Maximum value. Percentage or ratio value as documented.	56
`maxAvgBsr`	Integer	No	Max avg BSR. Maximum value.	100
`maxAvgPrice`	Number	No	Max avg price. Maximum value.	50
`maxAvgProfit`	Number	No	Max avg profit. Maximum value. Percentage or ratio value as documented.	70
`maxAvgRating`	Number	No	Max avg rating. Maximum value.	3
`maxAvgRatings`	Integer	No	Max avg ratings. Maximum value.	500
`maxAvgRevenue`	Number	No	Max avg revenue. Maximum value.	900
`maxAvgSellers`	Number	No	Max avg sellers. Maximum value.	10.4
`maxAvgUnits`	Integer	No	Max avg units. Maximum value.	10000
`maxBrandCrn`	Number	No	Max brand crn. Maximum value.	55
`maxBrands`	Integer	No	Max brands. Maximum value.	20
`maxEbcProportion`	Number	No	Max A+ content proportion. Maximum value. Percentage or ratio value as documented.	54
`maxFbaProportion`	Number	No	Max FBA proportion. Maximum value. Percentage or ratio value as documented.	54
`maxFbmProportion`	Number	No	Max FBM proportion. Maximum value. Percentage or ratio value as documented.	54
`maxGoodsCount`	Integer	No	Max goods count. Maximum value.	90
`maxGoodsCrn`	Number	No	Max goods crn. Maximum value.	55
`maxNewAvgPrice`	Number	No	Max new avg price. Maximum value.	45
`maxNewAvgRating`	Number	No	Max new avg rating. Maximum value.	4.5
`maxNewAvgRatings`	Integer	No	Max new avg ratings. Maximum value.	554
`maxNewAvgRevenue`	Number	No	Max new avg revenue. Maximum value.	2000
`maxNewAvgUnits`	Number	No	Max new avg units. Maximum value.	800
`maxNewCount`	Integer	No	Max new count. Maximum value.	20
`maxNewProportion`	Number	No	Max new proportion. Maximum value. Percentage or ratio value as documented.	56
`maxSellerCrn`	Number	No	Max seller crn. Maximum value.	45
`maxSellers`	Integer	No	Max sellers. Maximum value.	10
`maxTopAvgBsr`	Integer	No	Max top avg BSR. Maximum value.	998
`maxTopAvgRevenue`	Number	No	Max top avg revenue. Maximum value.	3000
`maxTopAvgUnits`	Integer	No	Max top avg units. Maximum value.	300
`maxVolume`	Number	No	Max volume. Maximum value.	50
`maxWeight`	Number	No	Max weight. Maximum value.	60
`minAmazonSelfProportion`	Number	No	Min Amazon self proportion. Minimum value. Percentage or ratio value as documented.	34
`minAvgBsr`	Integer	No	Min avg BSR. Minimum value.	50
`minAvgPrice`	Number	No	Min avg price. Minimum value.	30
`minAvgProfit`	Number	No	Min avg profit. Minimum value. Percentage or ratio value as documented.	20
`minAvgRating`	Number	No	Min avg rating. Minimum value.	2.5
`minAvgRatings`	Integer	No	Min avg ratings. Minimum value.	100
`minAvgRevenue`	Number	No	Min avg revenue. Minimum value.	100
`minAvgSellers`	Number	No	Min avg sellers. Minimum value.	4.4
`minAvgUnits`	Integer	No	Min avg units. Minimum value.	100
`minBrandCrn`	Number	No	Min brand crn. Minimum value.	45
`minBrands`	Integer	No	Min brands. Minimum value.	10
`minEbcProportion`	Number	No	Min A+ content proportion. Minimum value. Percentage or ratio value as documented.	34
`minFbaProportion`	Number	No	Min FBA proportion. Minimum value. Percentage or ratio value as documented.	34
`minFbmProportion`	Number	No	Min FBM proportion. Minimum value. Percentage or ratio value as documented.	34
`minGoodsCount`	Integer	No	Min goods count. Minimum value.	40
`minGoodsCrn`	Number	No	Min goods crn. Minimum value.	45
`minNewAvgPrice`	Number	No	Min new avg price. Minimum value.	34
`minNewAvgRating`	Number	No	Min new avg rating. Minimum value.	4
`minNewAvgRatings`	Integer	No	Min new avg ratings. Minimum value.	23
`minNewAvgRevenue`	Number	No	Min new avg revenue. Minimum value.	900
`minNewAvgUnits`	Number	No	Min new avg units. Minimum value.	400
`minNewCount`	Integer	No	Min new count. Minimum value.	4
`minNewProportion`	Number	No	Min new proportion. Minimum value. Percentage or ratio value as documented.	34
`minSellerCrn`	Number	No	Min seller crn. Minimum value.	55
`minSellers`	Integer	No	Min sellers. Minimum value.	6
`minTopAvgBsr`	Integer	No	Min top avg BSR. Minimum value.	68
`minTopAvgRevenue`	Number	No	Min top avg revenue. Minimum value.	2000
`minTopAvgUnits`	Integer	No	Min top avg units. Minimum value.	200
`minVolume`	Number	No	Min volume. Minimum value.	20
`minWeight`	Number	No	Min weight. Minimum value.	30
`month`	String	No	Data month. Use the format documented for this endpoint, usually yyyyMM.	202507
`newProduct`	Integer	No	New product. See the documented default in the example column.	3
`nodeIdPath`	String	No	Amazon category node path.	172282:281407
`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,currency,nodeId
`sellerLocation`	String	No	Seller location.	US,GB
`size`	Integer	No	Number of results per page.	50
`topNum`	Integer	No	Top num.	10

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
`currency`	String	Currency.	USD
`nodeId`	String	Node ID.	3732981
`nodeLabelName`	String	Node label name.	Mattresses
`nodeIdPath`	String	Node ID path.	1055398:1063306:1063308:3732961:3732981
`nodeLabelPath`	String	Node label path.	Home & Kitchen:Furniture:Bedroom Furniture:Mattresses & Box Springs:Mattresses
`nodeLabelLocale`	String	Node label locale.	床垫
`nodeLabelPathLocale`	String	Node label path locale.	家居用品厨房:家具:家具卧室:床垫:床垫
`totalProducts`	Integer	Total products.	1000
`ranking`	Integer	Ranking.	1
`topProducts`	Integer	Top products.	100
`brands`	Integer	Brands.	34
`sellers`	Integer	Sellers.	60
`totalUnits`	Integer	Total units.	539009
`totalRevenue`	Number	Total revenue.	179950610.4
`avgUnits`	Integer	Avg units.	5390
`avgRevenue`	Number	Avg revenue.	1799506
`avgPrice`	Number	Avg price.	296.11
`avgRatings`	Integer	Avg ratings.	14591
`avgRating`	Number	Avg rating.	4.5
`avgBsr`	Integer	Avg BSR.	198077
`baseAvgVolume`	Number	Base avg volume.	529430.46
`avgVolume`	Number	Avg volume.	32307.87
`baseAvgWeight`	Number	Base avg weight.	35301.19
`avgWeight`	Number	Avg weight.	77.8259
`avgProfit`	Number	Avg profit. Percentage or ratio value as documented.	68.76
`avgSellers`	Number	Avg sellers.	3.3
`ebcProportion`	Number	A+ content proportion. Percentage or ratio value as documented.	80
`amazonSelfProportion`	Number	Amazon self proportion. Percentage or ratio value as documented.	55
`fbaProportion`	Number	FBA proportion. Percentage or ratio value as documented.	22
`fbmProportion`	Number	FBM proportion. Percentage or ratio value as documented.	14
`sellerNation`	String	Seller nation.	US
`sellerNationLabel`	String	Seller nation label.	美国
`sellerProportion`	Number	Seller proportion. Percentage or ratio value as documented.	59.3
`top10Images`	Array	Top10 images.	-
`top10Images.asin`	String	ASIN.	B01IU6RJYA
`top10Images.image`	String	Image.	https://images-na.ssl-images-amazon.com/images/I/51+5VVLcXSL._AC_US200_.jpg
`returnRatio`	Number	Return ratio. Percentage or ratio value as documented.	3.51
`avgReturnRatio`	Number	Avg return ratio. Percentage or ratio value as documented.	5.54
`searchToPurchaseRatio`	Number	Search to purchase ratio.	0.94926
`top3ProductSales`	Integer	Top3 product sales.	-
`top3BrandSales`	Integer	Top3 brand sales.	-
`top3SellerSales`	Integer	Top3 seller sales.	-
`top3ProductRevenue`	Number	Top3 product revenue.	-
`top3BrandRevenue`	Number	Top3 brand revenue.	-
`top3SellerRevenue`	Number	Top3 seller revenue.	-
`top3ProductCrn`	Number	Top3 product crn.	-
`top3BrandCrn`	Number	Top3 brand crn.	-
`top3SellerCrn`	Number	Top3 seller crn.	-
`top5ProductSales`	Integer	Top5 product sales.	-
`top5BrandSales`	Integer	Top5 brand sales.	-
`top5SellerSales`	Integer	Top5 seller sales.	-
`top5ProductRevenue`	Number	Top5 product revenue.	-
`top5BrandRevenue`	Number	Top5 brand revenue.	-
`top5SellerRevenue`	Number	Top5 seller revenue.	-
`top5ProductCrn`	Number	Top5 product crn.	-
`top5BrandCrn`	Number	Top5 brand crn.	-
`top5SellerCrn`	Number	Top5 seller crn.	-
`top10ProductSales`	Integer	Top10 product sales.	-
`top10BrandSales`	Integer	Top10 brand sales.	-
`top10SellerSales`	Integer	Top10 seller sales.	-
`top10ProductRevenue`	Number	Top10 product revenue.	-
`top10BrandRevenue`	Number	Top10 brand revenue.	-
`top10SellerRevenue`	Number	Top10 seller revenue.	-
`top10ProductCrn`	Number	Top10 product crn.	-
`top10BrandCrn`	Number	Top10 brand crn.	-
`top10SellerCrn`	Number	Top10 seller crn.	-
`top20ProductSales`	Integer	Top20 product sales.	-
`top20BrandSales`	Integer	Top20 brand sales.	-
`top20SellerSales`	Integer	Top20 seller sales.	-
`top20ProductRevenue`	Number	Top20 product revenue.	-
`top20BrandRevenue`	Number	Top20 brand revenue.	-
`top20SellerRevenue`	Number	Top20 seller revenue.	-
`top20ProductCrn`	Number	Top20 product crn.	-
`top20BrandCrn`	Number	Top20 brand crn.	-
`top20SellerCrn`	Number	Top20 seller crn.	-
`l1NewRatio`	Number	L1 new ratio. Percentage or ratio value as documented.	-
`l1NewCount`	Integer	L1 new count.	-
`l1NewAvgPrice`	Number	L1 new avg price.	-
`l1NewAvgReviews`	Integer	L1 new avg reviews.	-
`l1NewAvgRating`	Number	L1 new avg rating.	-
`l1NewAvgSales`	Integer	L1 new avg sales.	-
`l1NewAvgRevenue`	Number	L1 new avg revenue.	-
`l3NewRatio`	Number	L3 new ratio. Percentage or ratio value as documented.	-
`l3NewCount`	Integer	L3 new count.	-
`l3NewAvgPrice`	Number	L3 new avg price.	-
`l3NewAvgReviews`	Integer	L3 new avg reviews.	-
`l3NewAvgRating`	Number	L3 new avg rating.	-
`l3NewAvgSales`	Integer	L3 new avg sales.	-
`l3NewAvgRevenue`	Number	L3 new avg revenue.	-
`l6NewRatio`	Number	L6 new ratio. Percentage or ratio value as documented.	-
`l6NewCount`	Integer	L6 new count.	-
`l6NewAvgPrice`	Number	L6 new avg price.	-
`l6NewAvgReviews`	Integer	L6 new avg reviews.	-
`l6NewAvgRating`	Number	L6 new avg rating.	-
`l6NewAvgSales`	Integer	L6 new avg sales.	-
`l6NewAvgRevenue`	Number	L6 new avg revenue.	-
`l12NewRatio`	Number	L12 new ratio. Percentage or ratio value as documented.	-
`l12NewCount`	Integer	L12 new count.	-
`l12NewAvgPrice`	Number	L12 new avg price.	-
`l12NewAvgReviews`	Integer	L12 new avg reviews.	-
`l12NewAvgRating`	Number	L12 new avg rating.	-
`l12NewAvgSales`	Integer	L12 new avg sales.	-
`l12NewAvgRevenue`	Number	L12 new avg revenue.	-

Response example

{
  "request_id": "8fb43e59-4ff9-4dc8-a4b7-2ed164e45ab8",
  "data": {
    "guestId": null,
    "pages": 40,
    "page": 1,
    "size": 1,
    "total": 40,
    "took": 0,
    "url": null,
    "order": {
      "field": "",
      "desc": true
    },
    "items": [
      {
        "marketplace": "US",
        "currency": "USD",
        "nodeId": 10967801,
        "nodeLabelName": "Power Strips",
        "nodeIdPath": "172282:281407:17854127011:10967801",
        "nodeLabelPath": "Electronics:Accessories & Supplies:Power Strips & Surge Protectors:Power Strips",
        "nodeLabelLocale": "剥线器",
        "nodeLabelPathLocale": "电子产品:辅料:剥线器:剥线器",
        "top10Images": [
          {
            "asin": "B09PDLBFKY",
            "image": "https://images-na.ssl-images-amazon.com/images/I/61NGPmmMAIL._AC_US200_.jpg"
          }
        ],
        "totalProducts": 2815,
        "ranking": 1,
        "topProducts": 100,
        "brands": 45,
        "sellers": 45,
        "totalUnits": 1487414,
        "totalRevenue": 22973201.92,
        "avgUnits": 14874,
        "avgRevenue": 229732,
        "avgPrice": 17.83,
        "avgRatings": 10756,
        "avgRating": 4.7,
        "avgBsr": 447,
        "baseAvgVolume": 462.27,
        "avgVolume": 28.21,
        "baseAvgWeight": 412.99,
        "avgWeight": 0.9105,
        "avgProfit": 60.3,
        "avgSellers": 1.6,
        "ebcProportion": 91,
        "amazonSelfProportion": 3,
        "fbaProportion": 96,
        "fbmProportion": 0,
        "sellerNation": "CN",
        "sellerNationLabel": "中国",
        "sellerProportion": 86,
        "returnRatio": 2.8739,
        "avgReturnRatio": 2.8656,
        "searchToPurchaseRatio": 17.91785
      }
    ],
    "terminal": null,
    "hasNextPage": null,
    "guestVisited": false
  }
}

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

Market Research

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

Market Research

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