SeerMarTech API 文档

主题

Amazon 商品已排名（Live） ​

POST /v3/dataforseo_labs/amazon/ranked_keywords/live

接口说明 ​

该接口用于返回指定 Amazon 商品在平台数据库中已取得排名的列表。返回结果与请求中传的 asin 强，可用于分析某个商品当前覆盖了哪些搜索词、对应搜索量，以及该商品在相应 Amazon SERP 中的展示位置。

  • 请求方式：POST
  • 接口地址：https://api.seermartech.cn/v3/dataforseo_labs/amazon/ranked_keywords/live

asin 是 Amazon 商品的唯一标识。若你尚未掌握目标商品的 asin，可通过商品检索接口获取。

计费与频率限制 ​

本接口按请求计费。原文未提供固定单价，因此无法换算参考人民币价格。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

频率限制如下：

  • 每分钟最多 2000 次 API 调用
  • 最多 30 个并发请求
  • POST 数据需使用 UTF-8 编码的 JSON
  • 请求体格式为 JSON 数组：[{ ... }]

请求参数 ​

以下字段用于设置任务。

字段名类型说明
asinstring商品 ID。填。Amazon 商品唯一标识（ASIN）。
location_namestring地区名。当未指定 location_code 时填。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地区。当前支持：美国、埃及、沙特阿拉伯、阿联。示例：United States
location_codeinteger地区编码。当未指定 location_name 时填。可通过 /v3/dataforseo_labs/locations_and_languages 获取。当前支持：美国、埃及、沙特阿拉伯、阿联。示例：2840
language_namestring语言名称。当未指定 language_code 时填。可通过 /v3/dataforseo_labs/locations_and_languages 获取。示例：English
language_codestring语言代码。当未指定 language_name 时填。可通过 /v3/dataforseo_labs/locations_and_languages 获取。示例：en
limitinteger返回结果中数量上限。可选。默认 100，最大 1000。
ignore_synonymsboolean是否忽略高度相似。可选。设为 true 时返回核心，排除高度相似词；默认 false。
filtersarray结果过滤条件数组。可选。最多同时设置 8 个过滤条件；条件之间需要设置逻辑运算符 and 或 or。支持的运算符：regex、not_regex、<、<=、>、>=、=、<>、in、not_in、like、not_like、match、not_match。like 和 not_like 支持 % 通任意长度字符串。更多规则可参考文档中的过滤器说明。
order_byarray排序规则。可选。可使用与 filters 中相同的字段进行排序。排序方向支持：asc 升序、desc 降序。单次请求最多设置 3 条排序规则。
offsetinteger返回结果数组的偏移量。可选。默认 0。例如设为 10，则跳过前 10 个，从后续结果开始返回。
tagstring自定义任务标识。可选。最长 255 个字符。便于你在响应中识别和匹任务。

过滤与排序 ​

filters 说明 ​

filters 支持多条件组合，可按、搜索量、排名等字段筛选结果。使用时需在条件之间显式设置逻辑：

  • and
  • or

支持操作符：

  • regex
  • not_regex
  • <
  • <=
  • >
  • >=
  • =
  • <>
  • in
  • not_in
  • like
  • not_like
  • match
  • not_match

说明：

  • like / not_like 支持 % 通符
  • 最多 8 个过滤条件

order_by 说明 ​

可按结果字段排序，常见排序方式：

  • asc：升序
  • desc：降序

注意：

  • 单次请求最多支持 3 条排序规则
  • 多个排序规则之间使用逗号分隔

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/dataforseo_labs/amazon/ranked_keywords/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "asin": "B00R92CL5E",
 "language_name": "English",
 "location_code": 2840
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/amazon/ranked_keywords/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "asin": "B00R92CL5E",
 "location_name": "United States",
 "language_name": "English"
 }
]

response = requests.post(url, headers=headers, json=data)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

const postData = [
 {
 asin: "B00R92CL5E",
 language_name: "English",
 location_code: 2840
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/amazon/ranked_keywords/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postData
})
 .then((response) => {
 // 输出返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应结构 ​

接口返回 JSON 编码数据，顶层 tasks 数组。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本。
status_codeinteger通用状态码。完整错误码请参考 /v3/appendix/errors。建议对异常和错误状态做完整处理。
status_messagestring通用状态信息。
timestring执行耗时，单位秒。
costfloat本次请求总费用，单位 USD。
tasks_countintegertasks 数组中的任务数。
tasks_errorintegertasks 数组中返回错误的任务数。
tasksarray任务结果数组。

tasks[] 字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger任务状态码，范围通常为 10000-60000。
status_messagestring任务状态说明。
timestring任务执行耗时，单位秒。
costfloat该任务费用，单位 USD。
result_countintegerresult 数组中的数量。
patharray请求路径。
dataobject含与请求中提交参数相同的数据。
resultarray返回结果数组。

result[] 字段 ​

字段名类型说明
se_typestring搜索引擎类型。
asinstring请求中提交的 ASIN。
location_codeinteger请求中的地区编码；若无数据则为 null。
language_codestring请求中的语言代码；若无数据则为 null。
total_countinteger数据库中与当前请求匹的总结果数。
items_countinteger当前 items 数组返回的结果数。
itemsarray已识别的及对应排名数据。

items[] 字段 ​

字段名类型说明
se_typestring搜索引擎类型。
keyword_dataobject信息。
ranked_serp_elementobject该商品在对应下命中的 SERP素数据。

keyword_data 字段 ​

字段名类型说明
se_typestring搜索引擎类型。
keywordstring返回的。
location_codeinteger请求中的地区编码。
language_codestring请求中的语言代码。
keyword_infoobject扩展信息。

keyword_info 字段 ​

字段名类型说明
se_typestring搜索引擎类型。
last_updated_timestring数据最后更新时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。示例：2019-11-15 12:57:46 +00:00
search_volumeinteger平均月搜索量，表示该在 Amazon 上的大致搜索次数。

ranked_serp_element 字段 ​

字段名类型说明
se_typestring搜索引擎类型。
serp_itemobject命中的 SERP素。
check_urlstring对应的 Amazon 搜索结果直链，可用于人工校验结果准确性。
serp_item_typesarray当前 SERP 中识别到的结果类型列表。可能值：amazon_serp、amazon_paid、editorial_recommendations、top_rated_from_our_brands、related_searches
se_results_countintegerAmazon SERP 总结果数。
last_updated_timestringSERP 数据最后更新时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
previous_updated_timestring上一次 SERP 数据更新时间，ISO 8601 格式，例如：2020-09-12T00:07:43.0733218Z

serp_item 支持的类型 ​

serp_item 可能返回以下类型：

  • amazon_serp
  • amazon_paid
  • editorial_recommendations
  • top_rated_from_our_brands
  • related_searches

，前四类商品型字段结构基本一致；related_searches 为搜索词结构。

商品型通用字段 ​

适用于：

  • amazon_serp
  • amazon_paid
  • editorial_recommendations
  • top_rated_from_our_brands
字段名类型说明
se_typestring搜索引擎类型。
typestring素类型。
rank_groupinteger在相同 type 分组的位置。不同类型不计该位置。
rank_absoluteinteger在整个 Amazon SERP 中的绝对排名。
positionstring素所在区域，可能值：left、right。
xpathstring素的 XPath。
domainstringAmazon 域名。
titlestring商品标题。
urlstring商品页 URL。
descriptionstring商品描述。
asinstring商品 ASIN。
image_urlstring搜索结果中的商品图片 URL。
price_fromfloat商品常规价格。示例：49.98
price_tofloat商品价格区间上限。示例：384.99
currencystring币种，ISO 4217 格式。示例：USD
special_offersarray特殊优惠信息，如优惠券、订省折扣等。
is_best_sellerboolean是否带有 “Best Seller” 标记。
is_amazon_choiceboolean是否带有 “Amazon's choice” 标记。
ratingobject商品评分信息。
delivery_infoobject送信息、快速时间范围等。

rating 字段 ​

字段名类型说明
rating_typestring评分类型，可能值：Max5、Percents、CustomMax
valueinteger评分值。
votes_countinteger评价数量。
rating_maxinteger当前评分类型的最大值。

delivery_info 字段 ​

字段名类型说明
delivery_messagestring卖家显示的提示信息。
delivery_priceobject送价格信息。若运费，则为 null。

delivery_price 字段 ​

字段名类型说明
currentfloat当前价格。
regularfloat原始未折扣价格。
max_valuefloat未折扣价格上限。
currencystring币种，ISO 4217 格式。
is_price_rangeboolean是否为价格区间。
displayed_pricestringAmazon 页面展示的价格文案。
字段名类型说明
se_typestring搜索引擎类型。
typestring素类型，固定为 related_searches。
rank_groupinteger在相同类型分组中的位置。
rank_absoluteinteger在整个 SERP 中的绝对位置。
xpathstring素 XPath。
itemsarray搜索项数组。
字段名类型说明
typestring素类型，固定为 related_searches_element。
titlestring搜索标题。
urlstring对应链接。
image_altstring图片 alt 文本。
image_urlstring图片 URL。

响应示例 ​

以下示例根据原始文档结构整理保留可读性较高的核心字段。

json
{
 "version": "0.1.20220216",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2091 sec.",
 "cost": 0.011,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "ranked_keywords",
 "se_type": "amazon",
 "asin": "B00R92CL5E",
 "location_code": 2840,
 "language_code": "en",
 "limit": 10
 },
 "result": [
 {
 "se_type": "amazon",
 "asin": "B00R92CL5E",
 "location_code": 2840,
 "language_code": "en",
 "items": [
 {
 "se_type": "amazon",
 "keyword_data": {
 "se_type": "amazon",
 "keyword": "car window stickers",
 "location_code": 2840,
 "language_code": "en",
 "keyword_info": {
 "se_type": "amazon",
 "last_updated_time": "2022-02-07 00:21:14 +00:00",
 "search_volume": 20900
 }
 },
 "ranked_serp_element": {
 "se_type": "amazon",
 "serp_item": {
 "se_type": "amazon",
 "type": "amazon_serp",
 "rank_group": 49,
 "rank_absolute": 53,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/span/div/div",
 "domain": "www.amazon.com",
 "title": "NETGEAR Wi-Fi Range Extender EX3700 - Coverage Up to 1000 Sq Ft...",
 "url": "https://www.amazon.com/NETGEAR-Wi-Fi-Range-Extender-EX3700/dp/B00R92CL5E/ref=sr_1_46?keywords=car+window+stickers&qid=1643909825&sr=8-46",
 "description": null,
 "asin": "B00R92CL5E",
 "image_url": null,
 "price_from": 39,
 "price_to": null,
 "currency": "USD",
 "special_offers": null,
 "is_best_seller": false,
 "is_amazon_choice": false,
 "rating": {
 "rating_type": "Max5",
 "value": 3,
 "votes_count": 68918,
 "rating_max": 5
 },
 "delivery_info": null
 },
 "check_url": "https://www.amazon.com/s/?field-keywords=car%20window%20stickers&page=1&language=en_US",
 "serp_item_types": [
 "amazon_serp"
 ],
 "se_results_count": 111829,
 "last_updated_time": "2022-02-04 12:37:22 +00:00",
 "previous_updated_time": null
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理 ​

  • 顶层 status_code 表示整次请求状态
  • tasks[].status_code 表示任务状态
  • 建议同时检查：
  • HTTP 状态码
  • 顶层 status_code
  • 任务级 tasks[].status_code

常见成功状态：

  • 20000：请求成功

完整错误码列表请参考 /v3/appendix/errors。生产环境中建议为限流、参数缺失、认证失败、额不足、平台暂时无数据等建立重试与告警机制。

使用建议 ​

  1. 优使用 location_code + language_code 编码形式更稳定，便于程序化管理。

  2. 按需设置 ignore_synonyms=true 如果你更核心词而非近义、变体词，建议开启，便于减少结果冗余。

  3. 通过 offset + limit 分页拉取 当一个商品命中的很多时，建议分页获取，一次请求返回过多数据。

  4. 结合 search_volume 与 rank_absolute 评估词价值 高搜索量且排名靠前的词，通常是值得重点保留和扩展的流量词。

实用场景 ​

  • 识别商品自然覆盖词：查看某个 ASIN 当前已经在哪些 Amazon 搜索词下有排名，帮助判断 Listing 的真实搜索可见度。
  • 筛选高价值流量词：结合 search_volume 和 rank_absolute，找出“搜索量高且已有一定排名”的词，优标题、五点描述和广告优化。
  • 监控排名下滑：定期查询同一 ASIN 的排名词变化，发现核心词排名下降时及时调整、价格或投放策略。
  • 挖掘竞品词库：对竞品 ASIN 批量调用本接口，提取已排名，快速建立竞品流量词单。
  • 验证类目与词路匹度：分析商品当前命中的是否与目标人群、类目意图一致， Listing 获得无效。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API