Product Research API Documentation

Filter Amazon products by category, sales, revenue, price, ratings, sellers, and listing attributes.

Availability: Available

This endpoint is active in the v1 gateway, OpenAPI, and subscription catalog. A successful call consumes 1 billing unit.

POST /v1/amazon/products/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/products/research \
  --header "Content-Type: application/json" \
  --header "X-API-Key: ${ECOMMERCE_DATA_API_KEY}" \
  --data '{
  "marketplace": "US",
  "month": "nearly",
  "keyword": "bath rug",
  "matchType": 2,
  "minPrice": 20,
  "maxPrice": 80,
  "minUnits": 500,
  "minRating": 4,
  "maxRatings": 3000,
  "variation": "Y",
  "page": 1,
  "size": 20,
  "order": {
    "field": "total_units",
    "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 "Product 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/products/research
Endpoint: POST https://ecommercedataapi.com/v1/amazon/products/research
API key environment variable: ECOMMERCE_DATA_API_KEY

Example request:
{
"marketplace": "US",
"month": "nearly",
"keyword": "bath rug",
"matchType": 2,
"minPrice": 20,
"maxPrice": 80,
"minUnits": 500,
"minRating": 4,
"maxRatings": 3000,
"variation": "Y",
"page": 1,
"size": 20,
"order": {
"field": "total_units",
"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/products/research',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.ECOMMERCE_DATA_API_KEY,
    },
    body: JSON.stringify({
      marketplace: 'US',
      month: 'nearly',
      keyword: 'bath rug',
      matchType: 2,
      minPrice: 20,
      maxPrice: 80,
      minUnits: 500,
      minRating: 4,
      maxRatings: 3000,
      variation: 'Y',
      page: 1,
      size: 20,
      order: {
        field: 'total_units',
        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/products/research",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["ECOMMERCE_DATA_API_KEY"],
    },
    json={
        "marketplace": "US",
        "month": "nearly",
        "keyword": "bath rug",
        "matchType": 2,
        "minPrice": 20,
        "maxPrice": 80,
        "minUnits": 500,
        "minRating": 4,
        "maxRatings": 3000,
        "variation": "Y",
        "page": 1,
        "size": 20,
        "order": {
            "field": "total_units",
            "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
`availableMonth`	Integer	No	Limit products by listing age: 1, 3, 6, 12, or 24 months. Omit the field for no listing-age restriction.	3
`badgeAC`	String	No	Set to Y to require an Amazon's Choice badge.	Y
`badgeBS`	String	No	Set to Y to require a Best Seller badge.	Y
`badgeNR`	String	No	Set to Y to require a New Release badge.	Y
`dimensionType`	String	No	Comma-separated product size-tier codes. Codes vary by marketplace; for example US values include ST, LS, SO, MO, LO, SP, O, ELO, EL5O, EL7O, and EL15O.	ST,LS
`excludeBrands`	String	No	Exclude products from the specified brand filter.	Generic
`excludeKeywords`	String	No	Keywords to exclude from the product results.	portable
`excludeSellers`	String	No	Exclude products matching the specified seller filter.	A1MCYUGJD2ILFU
`filterSub`	String	No	Set to Y to apply the subcategory-rank filters. It only takes effect when a category is specified.	Y
`fulfillment`	String	No	Fulfillment types separated by commas. Supported values are AMZ, FBA, and FBM.	FBA,FBM
`includeBrands`	String	No	Only include products from the specified brand filter.	OLANLY
`includeSellers`	String	No	Only include products matching the specified seller filter.	A1MCYUGJD2ILFU
`keyword`	String	No	Product keyword used to filter listing titles and related text.	bath rug
`marketplace`	String	Yes	Amazon marketplace code. Supported values: US, UK, DE, FR, IT, ES, MX, CA, AU, JP, IN, AE, and BR.	US
`matchType`	Integer	No	Keyword match mode: 1 for phrase match, 2 for broad match, or 3 for exact match. Defaults to 2.	2
`maxAmzUnit`	Integer	No	Maximum recent sales estimate for the current ASIN. This filter is available for latest-30-day queries.	10000
`maxBsr`	Integer	No	Worst boundary for the top-level Best Sellers Rank. Smaller BSR values indicate a better rank.	50000
`maxBsrCr`	Number	No	Maximum BSR change rate as a percentage value.	30
`maxBsrCv`	Integer	No	Maximum numeric BSR change for the selected month.	5000
`maxFba`	Number	No	Maximum estimated FBA fee in the marketplace currency.	20
`maxLqs`	Number	No	Maximum listing quality score.	100
`maxPrice`	Number	No	Maximum product price in the marketplace currency.	80
`maxProfit`	Number	No	Maximum estimated gross margin percentage.	80
`maxRating`	Number	No	Maximum average star rating.	5
`maxRatings`	Integer	No	Maximum total rating count.	3000
`maxRatingsCv`	Integer	No	Maximum number of newly added ratings in the selected month.	500
`maxRevenue`	Number	No	Maximum estimated monthly revenue in the marketplace currency.	1000000
`maxRevenueCr`	Number	No	Maximum monthly revenue growth rate as a percentage value.	100
`maxSellers`	Integer	No	Maximum number of sellers on the listing.	10
`maxSubBsrRank`	Integer	No	Maximum subcategory rank. Requires filterSub=Y.	100
`maxUnits`	Integer	No	Maximum estimated monthly sales for the parent listing.	50000
`maxUnitsCr`	Number	No	Maximum monthly sales growth rate as a percentage value.	100
`maxVariations`	Integer	No	Maximum variation count.	20
`maxWeights`	Number	No	Maximum product weight expressed in weightUnit.	5
`minAmzUnit`	Integer	No	Minimum recent sales estimate for the current ASIN. This filter is available for latest-30-day queries.	100
`minBsr`	Integer	No	Best boundary for the top-level Best Sellers Rank. Smaller BSR values indicate a better rank.	1
`minBsrCr`	Number	No	Minimum BSR change rate as a percentage value.	-30
`minBsrCv`	Integer	No	Minimum numeric BSR change for the selected month.	-5000
`minFba`	Number	No	Minimum estimated FBA fee in the marketplace currency.	2
`minLqs`	Number	No	Minimum listing quality score.	60
`minPrice`	Number	No	Minimum product price in the marketplace currency.	20
`minProfit`	Number	No	Minimum estimated gross margin percentage.	20
`minRating`	Number	No	Minimum average star rating.	4
`minRatings`	Integer	No	Minimum total rating count.	10
`minRatingsCv`	Integer	No	Minimum number of newly added ratings in the selected month.	10
`minRevenue`	Number	No	Minimum estimated monthly revenue in the marketplace currency.	10000
`minRevenueCr`	Number	No	Minimum monthly revenue growth rate as a percentage value.	0
`minSellers`	Integer	No	Minimum number of sellers on the listing.	1
`minSubBsrRank`	Integer	No	Minimum subcategory rank. Requires filterSub=Y.	1
`minUnits`	Integer	No	Minimum estimated monthly sales for the parent listing.	500
`minUnitsCr`	Number	No	Minimum monthly sales growth rate as a percentage value.	0
`minVariations`	Integer	No	Minimum variation count.	1
`minWeights`	Number	No	Minimum product weight expressed in weightUnit.	0.1
`month`	String	No	Data month. Use "nearly" for the latest 30 days or yyyyMM for a specific month within the previous 24 months.	nearly
`nodeIdPath`	String	No	Single Amazon category node path. Use the category endpoint to obtain a node path.	1055398:1063236:1063242
`nodeIdPathEqual`	Boolean	No	When true, match only the exact category path. When false, include its descendant categories. Defaults to false.	false
`nodeIdPaths`	Array	No	Amazon category node paths. Use the category endpoint to obtain node paths.	["1055398:1063236:1063242"]
`order`	Object	No	Sort definition.	{"field":"total_units","desc":true}
`order.desc`	Boolean	No	Use true for descending order or false for ascending order. Defaults to true.	true
`order.field`	String	No	Sort field: total_units, total_amount, bsr_rank, price, rating, reviews, profit, reviews_rate, available_date, or questions. Defaults to total_units.	total_units
`page`	Integer	No	Page number starting at 1. Defaults to 1. A query can return at most 2,000 records; narrow the filters to retrieve additional segments.	1
`returnFields`	String	No	Optional response-field selection string. Omit it to receive the standard response payload.	asin,title,price,units,revenue
`sellerNation`	String	No	Seller country or region codes. Multiple values can be separated by commas; common values include CN, HK, US, JP, DE, and FR.	CN,US
`size`	Integer	No	Results per page. Defaults to 50 and supports up to 100.	20
`variation`	String	No	Variation handling: N includes variation ASINs; Y excludes variation ASINs.	Y
`weightUnit`	String	No	Unit used by minWeights and maxWeights: g, kg, oz, or lb. Defaults to g.	lb

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
`asin`	String	ASIN.	B078J8VPVW
`brand`	String	Brand.	Pampers
`brandUrl`	String	Brand URL.	https://www.amazon.com/s?k=HP
`imageUrl`	String	Image URL.	https://images-na.ssl-images-amazon.com/images/I/51axlzme6aL .AC_US200.jpg
`title`	String	Title.	Diapers Size 2, 186 Count - Pampers Swaddlers Disposable Baby Diapers, ONE MONTH SUPPLY
`parent`	String	Parent.	B081RGNL17
`nodeId`	Integer	Node ID.	3741281
`nodeIdPath`	String	Node ID path.	2619525011:3741271:3741281
`nodeLabelPath`	String	Node label path.	Baby Products:Diapering:Disposable Diapers
`symbol`	String	Symbol.	Y
`bsrId`	String	BSR ID.	office-products
`bsr`	Integer	BSR.	1
`bsrCr`	Number	BSR change rate. Percentage or ratio value as documented.	926.67
`bsrCv`	Integer	BSR change value.	10
`units`	Integer	Units.	26289
`unitsGr`	Number	Units gr. Percentage or ratio value as documented.	-46.3
`amzUnit`	Integer	Amazon unit.	4000
`amzUnitDate`	Integer	Amazon unit date. Date or timestamp value.	1.70248E+12
`revenue`	Number	Revenue.	1693537.4
`price`	Number	Price.	64.42
`primePrice`	Number	Prime price.	42
`profit`	Number	Profit. Percentage or ratio value as documented.	63.92
`fba`	Number	FBA.	13.58
`ratings`	Integer	Ratings.	32004
`ratingsRate`	Number	Ratings rate. Percentage or ratio value as documented.	40.57
`rating`	Number	Rating.	4.8
`ratingsCv`	Integer	Ratings change value.	10666
`ratingDelta`	Integer	Rating delta.	0
`lqs`	Number	Listing quality score.	-
`availableDate`	Integer	Available date. Date or timestamp value.	1.45408E+12
`fulfillment`	String	Fulfillment.	AMZ or FBA or FBM
`variations`	Integer	Variations.	7
`sellers`	Integer	Sellers.	7
`sellerId`	String	Seller ID.	A1Y8BVAASXO4R7
`sellerName`	String	Seller name.	Amazon
`sellerNation`	String	Seller nation.	见表 1.5
`badge`	Object	Badge.	包括了下面 5 个标识
`badge.bestSeller`	String	Best seller.	Y 或者 N
`badge.amazonChoice`	String	Amazon choice.	Y 或者 N
`badge.newRelease`	String	New release.	Y 或者 N
`badge.ebc`	String	A+ content.	Y 或者 N
`badge.video`	String	Video.	Y 或者 N
`weight`	String	Weight.	8.88 pounds
`dimension`	String	Dimension.	13.3 x 15.8 x 10.6 inches
`dimensionsType`	String	Dimensions type.	ST,0V
`pkgDimensions`	String	Pkg dimensions.	14.3 x 16.8 x 12.6 inches
`pkgDimensionType`	String	Pkg dimension type.	-
`pkgWeight`	String	Pkg weight.	18.88 pounds
`subcategories`	Array	Subcategories.	-
`subcategories.code`	String	Code.	1063242
`subcategories.rank`	Integer	Rank.	1
`subcategories.label`	String	Label.	Bath Rugs
`sku`	String	Sku.	["Color: Beige","Size: 47 inches"]
`deliveryPrice`	Number	Delivery price.	4
`primePrice.amazonChoice`	String	Amazon choice.	Y 或者 N

Response example

{
  "request_id": "8fb43e59-4ff9-4dc8-a4b7-2ed164e45ab8",
  "data": {
    "pages": 8,
    "page": 1,
    "size": 20,
    "total": 153,
    "took": 186,
    "order": {
      "field": "total_units",
      "desc": true
    },
    "items": [
      {
        "asin": "B0DB5VT4QJ",
        "parent": "B0DP268C4Y",
        "brand": "Example Brand",
        "title": "Example absorbent bathroom rug",
        "imageUrl": "https://images.example.com/products/B0DB5VT4QJ.jpg",
        "nodeId": 1063242,
        "nodeIdPath": "1055398:1063236:1063242",
        "nodeLabelPath": "Home & Kitchen:Bath:Bath Rugs",
        "bsr": 13,
        "units": 158113,
        "revenue": 16059537,
        "price": 39.99,
        "profit": 71.71,
        "ratings": 18821,
        "rating": 4.4,
        "ratingsCv": 2179,
        "fulfillment": "FBA",
        "variations": 12,
        "sellers": 1,
        "sellerNation": "US",
        "badge": {
          "bestSeller": "#1 Best Seller in Bath Rugs",
          "amazonChoice": "N",
          "newRelease": "N",
          "ebc": "Y",
          "video": "N"
        },
        "subcategories": [
          {
            "code": "1063242",
            "rank": 1,
            "label": "Bath Rugs"
          }
        ]
      }
    ]
  }
}

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/products/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/products/research \
  --header "Content-Type: application/json" \
  --header "X-API-Key: ${ECOMMERCE_DATA_API_KEY}" \
  --data '{
  "marketplace": "US",
  "month": "nearly",
  "keyword": "bath rug",
  "matchType": 2,
  "minPrice": 20,
  "maxPrice": 80,
  "minUnits": 500,
  "minRating": 4,
  "maxRatings": 3000,
  "variation": "Y",
  "page": 1,
  "size": 20,
  "order": {
    "field": "total_units",
    "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 "Product 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/products/research',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.ECOMMERCE_DATA_API_KEY,
    },
    body: JSON.stringify({
      marketplace: 'US',
      month: 'nearly',
      keyword: 'bath rug',
      matchType: 2,
      minPrice: 20,
      maxPrice: 80,
      minUnits: 500,
      minRating: 4,
      maxRatings: 3000,
      variation: 'Y',
      page: 1,
      size: 20,
      order: {
        field: 'total_units',
        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/products/research",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["ECOMMERCE_DATA_API_KEY"],
    },
    json={
        "marketplace": "US",
        "month": "nearly",
        "keyword": "bath rug",
        "matchType": 2,
        "minPrice": 20,
        "maxPrice": 80,
        "minUnits": 500,
        "minRating": 4,
        "maxRatings": 3000,
        "variation": "Y",
        "page": 1,
        "size": 20,
        "order": {
            "field": "total_units",
            "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
`availableMonth`	Integer	No	Limit products by listing age: 1, 3, 6, 12, or 24 months. Omit the field for no listing-age restriction.	3
`badgeAC`	String	No	Set to Y to require an Amazon's Choice badge.	Y
`badgeBS`	String	No	Set to Y to require a Best Seller badge.	Y
`badgeNR`	String	No	Set to Y to require a New Release badge.	Y
`dimensionType`	String	No	Comma-separated product size-tier codes. Codes vary by marketplace; for example US values include ST, LS, SO, MO, LO, SP, O, ELO, EL5O, EL7O, and EL15O.	ST,LS
`excludeBrands`	String	No	Exclude products from the specified brand filter.	Generic
`excludeKeywords`	String	No	Keywords to exclude from the product results.	portable
`excludeSellers`	String	No	Exclude products matching the specified seller filter.	A1MCYUGJD2ILFU
`filterSub`	String	No	Set to Y to apply the subcategory-rank filters. It only takes effect when a category is specified.	Y
`fulfillment`	String	No	Fulfillment types separated by commas. Supported values are AMZ, FBA, and FBM.	FBA,FBM
`includeBrands`	String	No	Only include products from the specified brand filter.	OLANLY
`includeSellers`	String	No	Only include products matching the specified seller filter.	A1MCYUGJD2ILFU
`keyword`	String	No	Product keyword used to filter listing titles and related text.	bath rug
`marketplace`	String	Yes	Amazon marketplace code. Supported values: US, UK, DE, FR, IT, ES, MX, CA, AU, JP, IN, AE, and BR.	US
`matchType`	Integer	No	Keyword match mode: 1 for phrase match, 2 for broad match, or 3 for exact match. Defaults to 2.	2
`maxAmzUnit`	Integer	No	Maximum recent sales estimate for the current ASIN. This filter is available for latest-30-day queries.	10000
`maxBsr`	Integer	No	Worst boundary for the top-level Best Sellers Rank. Smaller BSR values indicate a better rank.	50000
`maxBsrCr`	Number	No	Maximum BSR change rate as a percentage value.	30
`maxBsrCv`	Integer	No	Maximum numeric BSR change for the selected month.	5000
`maxFba`	Number	No	Maximum estimated FBA fee in the marketplace currency.	20
`maxLqs`	Number	No	Maximum listing quality score.	100
`maxPrice`	Number	No	Maximum product price in the marketplace currency.	80
`maxProfit`	Number	No	Maximum estimated gross margin percentage.	80
`maxRating`	Number	No	Maximum average star rating.	5
`maxRatings`	Integer	No	Maximum total rating count.	3000
`maxRatingsCv`	Integer	No	Maximum number of newly added ratings in the selected month.	500
`maxRevenue`	Number	No	Maximum estimated monthly revenue in the marketplace currency.	1000000
`maxRevenueCr`	Number	No	Maximum monthly revenue growth rate as a percentage value.	100
`maxSellers`	Integer	No	Maximum number of sellers on the listing.	10
`maxSubBsrRank`	Integer	No	Maximum subcategory rank. Requires filterSub=Y.	100
`maxUnits`	Integer	No	Maximum estimated monthly sales for the parent listing.	50000
`maxUnitsCr`	Number	No	Maximum monthly sales growth rate as a percentage value.	100
`maxVariations`	Integer	No	Maximum variation count.	20
`maxWeights`	Number	No	Maximum product weight expressed in weightUnit.	5
`minAmzUnit`	Integer	No	Minimum recent sales estimate for the current ASIN. This filter is available for latest-30-day queries.	100
`minBsr`	Integer	No	Best boundary for the top-level Best Sellers Rank. Smaller BSR values indicate a better rank.	1
`minBsrCr`	Number	No	Minimum BSR change rate as a percentage value.	-30
`minBsrCv`	Integer	No	Minimum numeric BSR change for the selected month.	-5000
`minFba`	Number	No	Minimum estimated FBA fee in the marketplace currency.	2
`minLqs`	Number	No	Minimum listing quality score.	60
`minPrice`	Number	No	Minimum product price in the marketplace currency.	20
`minProfit`	Number	No	Minimum estimated gross margin percentage.	20
`minRating`	Number	No	Minimum average star rating.	4
`minRatings`	Integer	No	Minimum total rating count.	10
`minRatingsCv`	Integer	No	Minimum number of newly added ratings in the selected month.	10
`minRevenue`	Number	No	Minimum estimated monthly revenue in the marketplace currency.	10000
`minRevenueCr`	Number	No	Minimum monthly revenue growth rate as a percentage value.	0
`minSellers`	Integer	No	Minimum number of sellers on the listing.	1
`minSubBsrRank`	Integer	No	Minimum subcategory rank. Requires filterSub=Y.	1
`minUnits`	Integer	No	Minimum estimated monthly sales for the parent listing.	500
`minUnitsCr`	Number	No	Minimum monthly sales growth rate as a percentage value.	0
`minVariations`	Integer	No	Minimum variation count.	1
`minWeights`	Number	No	Minimum product weight expressed in weightUnit.	0.1
`month`	String	No	Data month. Use "nearly" for the latest 30 days or yyyyMM for a specific month within the previous 24 months.	nearly
`nodeIdPath`	String	No	Single Amazon category node path. Use the category endpoint to obtain a node path.	1055398:1063236:1063242
`nodeIdPathEqual`	Boolean	No	When true, match only the exact category path. When false, include its descendant categories. Defaults to false.	false
`nodeIdPaths`	Array	No	Amazon category node paths. Use the category endpoint to obtain node paths.	["1055398:1063236:1063242"]
`order`	Object	No	Sort definition.	{"field":"total_units","desc":true}
`order.desc`	Boolean	No	Use true for descending order or false for ascending order. Defaults to true.	true
`order.field`	String	No	Sort field: total_units, total_amount, bsr_rank, price, rating, reviews, profit, reviews_rate, available_date, or questions. Defaults to total_units.	total_units
`page`	Integer	No	Page number starting at 1. Defaults to 1. A query can return at most 2,000 records; narrow the filters to retrieve additional segments.	1
`returnFields`	String	No	Optional response-field selection string. Omit it to receive the standard response payload.	asin,title,price,units,revenue
`sellerNation`	String	No	Seller country or region codes. Multiple values can be separated by commas; common values include CN, HK, US, JP, DE, and FR.	CN,US
`size`	Integer	No	Results per page. Defaults to 50 and supports up to 100.	20
`variation`	String	No	Variation handling: N includes variation ASINs; Y excludes variation ASINs.	Y
`weightUnit`	String	No	Unit used by minWeights and maxWeights: g, kg, oz, or lb. Defaults to g.	lb

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
`asin`	String	ASIN.	B078J8VPVW
`brand`	String	Brand.	Pampers
`brandUrl`	String	Brand URL.	https://www.amazon.com/s?k=HP
`imageUrl`	String	Image URL.	https://images-na.ssl-images-amazon.com/images/I/51axlzme6aL .AC_US200.jpg
`title`	String	Title.	Diapers Size 2, 186 Count - Pampers Swaddlers Disposable Baby Diapers, ONE MONTH SUPPLY
`parent`	String	Parent.	B081RGNL17
`nodeId`	Integer	Node ID.	3741281
`nodeIdPath`	String	Node ID path.	2619525011:3741271:3741281
`nodeLabelPath`	String	Node label path.	Baby Products:Diapering:Disposable Diapers
`symbol`	String	Symbol.	Y
`bsrId`	String	BSR ID.	office-products
`bsr`	Integer	BSR.	1
`bsrCr`	Number	BSR change rate. Percentage or ratio value as documented.	926.67
`bsrCv`	Integer	BSR change value.	10
`units`	Integer	Units.	26289
`unitsGr`	Number	Units gr. Percentage or ratio value as documented.	-46.3
`amzUnit`	Integer	Amazon unit.	4000
`amzUnitDate`	Integer	Amazon unit date. Date or timestamp value.	1.70248E+12
`revenue`	Number	Revenue.	1693537.4
`price`	Number	Price.	64.42
`primePrice`	Number	Prime price.	42
`profit`	Number	Profit. Percentage or ratio value as documented.	63.92
`fba`	Number	FBA.	13.58
`ratings`	Integer	Ratings.	32004
`ratingsRate`	Number	Ratings rate. Percentage or ratio value as documented.	40.57
`rating`	Number	Rating.	4.8
`ratingsCv`	Integer	Ratings change value.	10666
`ratingDelta`	Integer	Rating delta.	0
`lqs`	Number	Listing quality score.	-
`availableDate`	Integer	Available date. Date or timestamp value.	1.45408E+12
`fulfillment`	String	Fulfillment.	AMZ or FBA or FBM
`variations`	Integer	Variations.	7
`sellers`	Integer	Sellers.	7
`sellerId`	String	Seller ID.	A1Y8BVAASXO4R7
`sellerName`	String	Seller name.	Amazon
`sellerNation`	String	Seller nation.	见表 1.5
`badge`	Object	Badge.	包括了下面 5 个标识
`badge.bestSeller`	String	Best seller.	Y 或者 N
`badge.amazonChoice`	String	Amazon choice.	Y 或者 N
`badge.newRelease`	String	New release.	Y 或者 N
`badge.ebc`	String	A+ content.	Y 或者 N
`badge.video`	String	Video.	Y 或者 N
`weight`	String	Weight.	8.88 pounds
`dimension`	String	Dimension.	13.3 x 15.8 x 10.6 inches
`dimensionsType`	String	Dimensions type.	ST,0V
`pkgDimensions`	String	Pkg dimensions.	14.3 x 16.8 x 12.6 inches
`pkgDimensionType`	String	Pkg dimension type.	-
`pkgWeight`	String	Pkg weight.	18.88 pounds
`subcategories`	Array	Subcategories.	-
`subcategories.code`	String	Code.	1063242
`subcategories.rank`	Integer	Rank.	1
`subcategories.label`	String	Label.	Bath Rugs
`sku`	String	Sku.	["Color: Beige","Size: 47 inches"]
`deliveryPrice`	Number	Delivery price.	4
`primePrice.amazonChoice`	String	Amazon choice.	Y 或者 N

Response example

{
  "request_id": "8fb43e59-4ff9-4dc8-a4b7-2ed164e45ab8",
  "data": {
    "pages": 8,
    "page": 1,
    "size": 20,
    "total": 153,
    "took": 186,
    "order": {
      "field": "total_units",
      "desc": true
    },
    "items": [
      {
        "asin": "B0DB5VT4QJ",
        "parent": "B0DP268C4Y",
        "brand": "Example Brand",
        "title": "Example absorbent bathroom rug",
        "imageUrl": "https://images.example.com/products/B0DB5VT4QJ.jpg",
        "nodeId": 1063242,
        "nodeIdPath": "1055398:1063236:1063242",
        "nodeLabelPath": "Home & Kitchen:Bath:Bath Rugs",
        "bsr": 13,
        "units": 158113,
        "revenue": 16059537,
        "price": 39.99,
        "profit": 71.71,
        "ratings": 18821,
        "rating": 4.4,
        "ratingsCv": 2179,
        "fulfillment": "FBA",
        "variations": 12,
        "sellers": 1,
        "sellerNation": "US",
        "badge": {
          "bestSeller": "#1 Best Seller in Bath Rugs",
          "amazonChoice": "N",
          "newRelease": "N",
          "ebc": "Y",
          "video": "N"
        },
        "subcategories": [
          {
            "code": "1063242",
            "rank": 1,
            "label": "Bath Rugs"
          }
        ]
      }
    ]
  }
}

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

Product 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

Product 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