选产品
按类目、销量、销售额、价格、评分、卖家和 Listing 条件筛选 Amazon 商品。
API 数据样例
直接查看该接口实际使用的请求体和完整响应结构。
{
"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
}
}{
"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"
}
]
}
]
}
}可用状态:已开放
该接口已进入 v1 网关、OpenAPI 和订阅权限目录,成功调用一次消耗 1 个计费单位。
POST /v1/amazon/product/research
下方请求和响应字段已与当前公开契约核对。
接口对应关系
| 项目 | 内容 |
|---|---|
| MCP Code | product_research |
| 原始 REST 方法 | POST |
| 原始 REST 路径 | /v1/product/research |
| 原始 API 文档 | 打开官方 API 文档 |
历史路径仍可调用,但已弃用:
/v1/amazon/products/research。兼容请求会返回Deprecation: true和指向规范路径的Link响应头。
快速调用
先创建 API 密钥,再将密钥写入服务端环境变量:
export ECOMMERCE_DATA_API_KEY="your_api_key"curl --request POST \
--url https://ecommercedataapi.com/v1/amazon/product/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
}
}'使用 AI CLI 接入
复制给 AI CLI
粘贴到 Codex、Claude Code、Gemini CLI 或其他编程智能体中直接完成接入。
请直接在当前代码库中接入 Ecommerce Data API 的「选产品」接口,不要只给示例代码。
接口文档:https://ecommercedataapi.com/zh/docs/amazon/product/research
请求接口:POST https://ecommercedataapi.com/v1/amazon/product/research
API 密钥环境变量:ECOMMERCE_DATA_API_KEY
请求示例:
{
"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
}
}
请按以下要求执行:
1. 先阅读接口文档,并检查当前项目使用的语言、框架、HTTP 客户端、目录结构和环境变量约定。
2. 优先复用项目现有的 API 客户端和错误处理方式;如果没有,再创建最小可复用的 Ecommerce Data API 客户端与该接口调用封装。
3. 从服务端环境变量 ECOMMERCE_DATA_API_KEY 读取密钥,发送 Content-Type: application/json 和 X-API-Key 请求头。绝不能把真实密钥写入源码、前端代码、日志、测试快照或 Git。
4. 如果环境变量不存在,提示我自行设置 ECOMMERCE_DATA_API_KEY;不要索取、输出或猜测真实密钥,并继续完成不依赖真实请求的代码与测试。
5. 根据接口文档实现请求与响应类型,处理非 2xx 响应、request_id、error.code、error.message 和 429 限流。
6. 添加一个符合当前项目习惯的最小调用示例或测试。如果密钥已配置且当前环境允许外部请求,再执行一次最小真实调用;否则使用 mock 或静态验证。
7. 运行相关格式化、类型检查和测试,最后汇报修改文件、调用方法、验证结果以及仍需我配置的环境变量。还没有 API 密钥?创建 API 密钥
在 Postman 中打开当前请求
下载当前接口的预配置 Collection,再通过 Postman Import 导入。
导入后在 Collection Variables 中填写 apiKey。创建 API 密钥
Node.js 示例
const response = await fetch(
'https://ecommercedataapi.com/v1/amazon/product/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 示例
import os
import requests
response = requests.post(
"https://ecommercedataapi.com/v1/amazon/product/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"])请求参数
请求体直接发送下表字段,不要再包裹额外对象;未定义字段会被拒绝。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
availableMonth | 整数 | 否 | 上架月份 使用国家或地区编码,默认不限制 | 3 |
badgeAC | 字符串 | 否 | 是否有热销标识 Amazon's Choice | Y |
badgeBS | 字符串 | 否 | 是否有热销标识 Best Seller | Y |
badgeNR | 字符串 | 否 | 是否有新品标识 New Release | Y |
dimensionType | 字符串 | 否 | 尺寸类型集合,逗号分隔,默认不限制 见表 1.4 | ST,LS |
excludeBrands | 字符串 | 否 | 排除品牌 | Generic |
excludeKeywords | 字符串 | 否 | 排除的关键字 | portable |
excludeSellers | 字符串 | 否 | 排除卖家 | A1MCYUGJD2ILFU |
filterSub | 字符串 | 否 | 是否筛选子类目,Y:是 | Y |
fulfillment | 字符串 | 否 | 配送方式,多条件查询用逗号隔开 | FBA,FBM |
includeBrands | 字符串 | 否 | 包含品牌 | OLANLY |
includeSellers | 字符串 | 否 | 包含卖家 | A1MCYUGJD2ILFU |
keyword | 字符串 | 否 | 关键字 | bath rug |
marketplace | 字符串 | 是 | 市场编码 支持的市场编码见 OpenAPI 枚举 可选值:US、UK、DE、FR、IT、ES、MX、CA、AU、JP、IN、AE、BR。 | US |
matchType | 整数 | 否 | 匹配方式,1词组匹配 2模糊匹配 3精准匹配;默认2 | 2 |
maxAmzUnit | 整数 | 否 | 最高月子体销量 | 10000 |
maxBsr | 整数 | 否 | 大类 BSR 最高排名 | 50000 |
maxBsrCr | 数字 | 否 | BSR 最高增长率 | 30 |
maxBsrCv | 整数 | 否 | BSR 最高增长数 | 5000 |
maxFba | 数字 | 否 | FBA 最高运费 | 20 |
maxLqs | 数字 | 否 | 最高 Listing 页面质量分 | 100 |
maxPrice | 数字 | 否 | 最高价格 | 80 |
maxProfit | 数字 | 否 | 最大毛利率 | 80 |
maxRating | 数字 | 否 | 最高评分值 | 5 |
maxRatings | 整数 | 否 | 最高评分数 | 3000 |
maxRatingsCv | 整数 | 否 | 最高月新增评分数 | 500 |
maxRevenue | 数字 | 否 | 最高月销售额 | 1000000 |
maxRevenueCr | 数字 | 否 | 月销售额最高增长率 | 100 |
maxSellers | 整数 | 否 | 最大卖家数量 | 10 |
maxSubBsrRank | 整数 | 否 | 最大子类排名 | 100 |
maxUnits | 整数 | 否 | 最高月销量 | 50000 |
maxUnitsCr | 数字 | 否 | 月销量最高增长率 | 100 |
maxVariations | 整数 | 否 | 最高变体数 | 20 |
maxWeights | 数字 | 否 | 最大重量 | 5 |
minAmzUnit | 整数 | 否 | 最低月子体销量 | 100 |
minBsr | 整数 | 否 | 大类 BSR 最低排名 | 1 |
minBsrCr | 数字 | 否 | BSR 最低增长率 | -30 |
minBsrCv | 整数 | 否 | BSR 最低增长数 | -5000 |
minFba | 数字 | 否 | FBA 最低运费 | 2 |
minLqs | 数字 | 否 | 最低 Listing 页面质量分 | 60 |
minPrice | 数字 | 否 | 最低价格 | 20 |
minProfit | 数字 | 否 | 最小毛利率 | 20 |
minRating | 数字 | 否 | 最低评分值 | 4 |
minRatings | 整数 | 否 | 最低评分数 | 10 |
minRatingsCv | 整数 | 否 | 最低月新增评分数 | 10 |
minRevenue | 数字 | 否 | 最低月销售额 | 10000 |
minRevenueCr | 数字 | 否 | 月销售额最低增长率 | 0 |
minSellers | 整数 | 否 | 最小卖家数量 | 1 |
minSubBsrRank | 整数 | 否 | 最小子类排名 | 1 |
minUnits | 整数 | 否 | 最低月销量 | 500 |
minUnitsCr | 数字 | 否 | 月销量最低增长率 | 0 |
minVariations | 整数 | 否 | 最低变体数 | 1 |
minWeights | 数字 | 否 | 最小重量 | 0.1 |
month | 字符串 | 否 | 查询月份 格式:yyyyMM,示例:202507,按接口要求传入月份或日期 | nearly |
nodeIdPath | 字符串 | 否 | Amazon 类目节点路径。 | 1055398:1063236:1063242 |
nodeIdPathEqual | 布尔值 | 否 | true为类目精确查询 false为查询当前及子类目 默认false | false |
nodeIdPaths | 数组 | 否 | 类目节点字符串列表 可通过商品类目接口查询接口 | ["1055398:1063236:1063242"] |
order | 对象 | 否 | 排序 | {"field":"total_units","desc":true} |
order.desc | 布尔值 | 否 | 排序方式 true:desc,false:asc;默认:true | true |
order.field | 字符串 | 否 | 排序字段,默认:total_units 可用值见排序字段说明 | total_units |
page | 整数 | 否 | 页码,从 1 开始 默认:1,总条数限制2000条,可以细分条件拉取整个类目数据 最小值:1。 | 1 |
returnFields | 字符串 | 否 | 可选的返回字段选择字符串;不传时返回标准字段。 | asin,title,price,units,revenue |
sellerNation | 字符串 | 否 | 卖家所属地,默认不限制,多条件查询用逗号隔开 见表 1.5 | CN,US |
size | 整数 | 否 | 每页条数 默认:50,最大:100 最小值:1。 | 20 |
variation | 字符串 | 否 | 是否查询变体 asin N: 含变体, Y: 不含变体 | Y |
weightUnit | 字符串 | 否 | 重量单位,默认:g 见表2.7 | lb |
返回结构
| 字段 | 类型 | 说明 |
|---|---|---|
request_id | 字符串 | 本次请求的唯一标识。 |
data | 对象 | 接口业务数据。 |
下表字段位于 data 内。数组接口描述的是单个数组元素,分页接口描述的是 items[] 中的单条记录。
返回字段
| 字段 | 类型 | 说明 | 示例 |
|---|---|---|---|
asin | 字符串 | asin | B078J8VPVW |
brand | 字符串 | 品牌 | Pampers |
brandUrl | 字符串 | 品牌 URL | https://www.amazon.com/s?k=HP |
imageUrl | 字符串 | 图片 URL | https://images-na.ssl-images-amazon.com/images/I/51axlzme6aL .AC_US200.jpg |
title | 字符串 | 商品标题 | Diapers Size 2, 186 Count - Pampers Swaddlers Disposable Baby Diapers, ONE MONTH SUPPLY |
parent | 字符串 | 父体 | B081RGNL17 |
nodeId | 整数 | 节点 id | 3741281 |
nodeIdPath | 字符串 | 节点 id 路径字符串 | 2619525011:3741271:3741281 |
nodeLabelPath | 字符串 | 类目 | Baby Products:Diapering:Disposable Diapers |
symbol | 字符串 | 是否畅销 | Y |
bsrId | 字符串 | BSRid | office-products |
bsr | 整数 | BSR 排名 | 1 |
bsrCr | 数字 | BSR 增长率 | 926.67 |
bsrCv | 整数 | BSR 增长数 | 10 |
units | 整数 | 月销量(父) | 26289 |
unitsGr | 数字 | 月销量增长率 | -46.3 |
amzUnit | 整数 | 子体近30日销量(仅近30日查询支持) | 4000 |
amzUnitDate | 整数 | 子体销量更新日期 | 1.70248E+12 |
revenue | 数字 | 月销售额(父体) | 1693537.4 |
price | 数字 | 价格 | 64.42 |
primePrice | 数字 | prime价格,-1表示没有 | 42 |
profit | 数字 | 利润率 | 63.92 |
fba | 数字 | fba 运费 | 13.58 |
ratings | 整数 | 评分数 | 32004 |
ratingsRate | 数字 | 留评率 | 40.57 |
rating | 数字 | 评分 | 4.8 |
ratingsCv | 整数 | 月度增长数 | 10666 |
ratingDelta | 整数 | 留评数:近 30 天新增评论数 | 0 |
lqs | 数字 | listing质量得分 | - |
availableDate | 整数 | 上架时间,时间戳格式 | 1.45408E+12 |
fulfillment | 字符串 | 配送方式 | AMZ or FBA or FBM |
variations | 整数 | 变体数 | 7 |
sellers | 整数 | 卖家数 | 7 |
sellerId | 字符串 | BuyBox 卖家 id | A1Y8BVAASXO4R7 |
sellerName | 字符串 | BuyBox 卖家 | Amazon |
sellerNation | 字符串 | BuyBox 卖家国籍 | 见表 1.5 |
badge | 对象 | 标识 | 包括了下面 5 个标识 |
badge.bestSeller | 字符串 | Best Seller 标识 | Y 或者 N |
badge.amazonChoice | 字符串 | amazon choice 标识 | Y 或者 N |
badge.newRelease | 字符串 | release 标识 | Y 或者 N |
badge.ebc | 字符串 | A+页面 | Y 或者 N |
badge.video | 字符串 | 视频介绍 | Y 或者 N |
weight | 字符串 | 重量 | 8.88 pounds |
dimension | 字符串 | 尺寸 | 13.3 x 15.8 x 10.6 inches |
dimensionsType | 字符串 | 尺寸类型 | ST,0V |
pkgDimensions | 字符串 | 包装尺寸 | 14.3 x 16.8 x 12.6 inches |
pkgDimensionType | 字符串 | 包装尺寸类型 | - |
pkgWeight | 字符串 | 包装重量 | 18.88 pounds |
subcategories | 数组 | 子类目 | - |
subcategories.code | 字符串 | 类目code | 1063242 |
subcategories.rank | 整数 | 排名 | 1 |
subcategories.label | 字符串 | 名称 | Bath Rugs |
sku | 字符串 | sku | ["Color: Beige","Size: 47 inches"] |
deliveryPrice | 数字 | 卖家运费,-1表示没有 | 4 |
primePrice.amazonChoice | 字符串 | amazon choice 标识 | Y 或者 N |
返回示例
{
"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"
}
]
}
]
}
}错误响应、请求追踪和限流头说明见错误与限流。
可组合使用的 AI Skills 与 Agents
从业务任务出发,查看这些能力如何使用当前 API,并在安装前审阅来源与权限。
Ecommerce Data API Agent Skill
在支持的 AI 编程 Agent 中发现、检查并调用实时 Amazon 商品、关键词、市场、流量、评论和商标 API。
Amazon 产品经理决策 Skill
将市场筛选、选品、单位经济、Listing、PPC、库存、发布、增长和止损决策连接成统一运营流程。
Amazon 选产品 Skill
评估 Amazon 商品机会的需求、竞争、利润潜力、进入壁垒、供应链和上市假设。
TikTok Shop 跨境扩张 Skill
规划 TikTok Shop 市场进入、物流、本地化、达人运营、税务、合规和国际上线。