SeerMarTech API 文档

主题

按任务 ID 获取 Amazon 商品高级搜索结果 ​

GET /v3/merchant/amazon/products/tasks_ready

GET /v3/merchant/amazon/products/task_get/advanced/$id

通过已提交任务的唯一标识符获取 Amazon 商品搜索高级结果。任务结果自创建起保留 30 天，在有效期可重复查询；费用在提交任务时产生。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数 ​

参数类型填说明
idstring是任务唯一标识符，采用 UUID 格式。例如：04170913-0696-0179-0000-707d6a06f64b。可在任务提交后的 30 天用于查询结果。

请求示例 ​

curl ​

bash
task_id="04170913-0696-0179-0000-707d6a06f64b"

curl --location --request GET \
  "https://api.seermartech.cn/v3/merchant/amazon/products/task_get/advanced/${task_id}" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

Python ​

python
import requests

task_id = "04170913-0696-0179-0000-707d6a06f64b"
url = (
    "https://api.seermartech.cn/"
    f"v3/merchant/amazon/products/task_get/advanced/{task_id}"
)

response = requests.get(
    url,
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
    timeout=60,
)

response.raise_for_status()
result = response.json()

# 检查接口及任务状态
if result["status_code"] == 20000:
    task = result["tasks"][0]
    if task["status_code"] < 40000:
        print(task["result"])
    else:
        print(f"任务错误：{task['status_code']} - {task['status_message']}")
else:
    print(f"请求错误：{result['status_code']} - {result['status_message']}")

TypeScript ​

typescript
import axios from "axios";

const taskId = "04170913-0696-0179-0000-707d6a06f64b";

async function getAmazonProductsResult() {
  const response = await axios.get(
    `https://api.seermartech.cn/v3/merchant/amazon/products/task_get/advanced/${taskId}`,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    },
  );

  const data = response.data;

  // 检查接口状态及任务执行状态
  if (data.status_code === 20000 && data.tasks?.[0]?.status_code < 40000) {
    console.log(data.tasks[0].result);
  } else {
    console.error(data.status_message);
  }
}

getAmazonProductsResult().catch(console.error);

响应结构 ​

接口返回 JSON 对象，顶层 tasks 数组。每个任务对象对应一个已提交的商品搜索任务。

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger接口通用状态码。20000 表示请求成功。建议针对异常和错误状态建立处理机制。
status_messagestring接口通用状态说明。
timestring请求执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数量。
tasks_errorinteger返回错误的任务数量。
tasksarray任务结果数组。

tasks[] 任务字段 ​

字段类型说明
idstring任务 UUID。
status_codeinteger任务状态码，取值通常在 10000 至 60000 范围。
status_messagestring任务状态说明。
timestring任务执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的结果对象数量。
patharray用于获取该任务结果的 API 路径。
dataobject创建任务时提交的原始参数。
resultarray商品搜索结果数组。

tasks[].result[] 搜索结果字段 ​

字段类型说明
keywordstring提交任务时使用的。URL 编码会被解码，+ 会还原为空格。
typestring创建任务时指定的搜索引擎类型。
se_domainstring创建任务时指定的搜索域名。
location_codeinteger创建任务时指定的地区代码。
language_codestring创建任务时指定的语言代码。
check_urlstringAmazon 搜索结果页直达链接，可用于人工核验结果。
datetimestring获取结果的 UTC 时间，格式为 yyyy-mm-dd hh-mm-ss +00:00。
spellobject搜索引擎自动纠错信息；未发生纠错时可能为 null。
spell.keywordstring自动纠正后的。结果基于该返回。
spell.typestring自动纠错类型：did_you_mean、showing_results_for、no_results_found_for 或 including_results_for。
item_typesarray本次 SERP 中发现的结果类型集合。
se_results_countinteger搜索引擎返回的结果总数。
categoriesarrayAmazon 商品部门及子分类信息。
items_countintegeritems 数组中的结果数量。
itemsarrayAmazon SERP素数组。

item_types 可能以下值：

  • amazon_serp：自然商品结果；
  • amazon_paid：推广商品结果；
  • editorial_recommendations：编辑推荐模块；
  • top_rated_from_our_brands：高评分自有品牌模块；
  • related_searches：搜索模块。

SERP素类型 ​

items[] 中的通过 type 字段区分模块类型。不同模块的排名字段如下。

字段类型说明
typestringSERP素类型。
rank_groupinteger同类型组的位置；不计类型。
rank_absoluteinteger在 Amazon SERP素中的绝对位置。
positionstring素在页面中的布局位置，可为 left 或 right。
xpathstring素在页面中的 XPath 路径。

amazon_serp：自然商品结果 ​

type 为 amazon_serp 的表示常规商品搜索结果。

amazon_paid：推广商品结果 ​

type 为 amazon_paid 的表示 Amazon 赞助或付费商品结果。

商品字段 ​

amazon_serp、amazon_paid 以及推荐模块中的商品均可能以下字段。

字段类型说明
domainstringAmazon 域名，例如 www.amazon.com。
titlestring商品标题。
urlstring商品页 URL。
image_urlstring搜索结果中展示的商品图片 URL。
bought_past_monthinteger最近一个月的商品购买量；无数据时为 null。
price_fromfloat商品常规价格或价格区间下限，例如 49.98。
price_tofloat商品价格区间上限；非价格区间时通常为 null。
currencystring货币代码，采用 ISO 4217 格式，例如 USD。
special_offersarray特惠信息优惠券、订省折扣等；无数据时为 null。
data_asinstringAmazon 商品唯一标识符（ASIN），例如 B07G82D89J。该字段由 Amazon 动态分。
ratingobject商品评分信息。
is_amazon_choiceboolean是否带有 Amazon's Choice 标签。
is_best_sellerboolean是否带有 Best Seller 标签。
delivery_infoobject送信息时间和运费。
labelsarray商品标签信息；没有标签时为 null。

rating 评分字段 ​

字段类型说明
typestring固定为 rating_element。
positionstring评分布局位置，可为 left 或 right。
rating_typestring评分类型，可为 Max5、Percents 或 CustomMax。
valuefloat当前评分值。
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 页面展示的原始运费文本。

labels 商品标签字段 ​

字段类型说明
typestring固定为 amazon_label_element。
titlestring标签标题，例如 Audiobook。
urlstring标签商品链接的 URL。
domainstring标签链接中的域名；Amazon 标签通常为 null。

editorial_recommendations：编辑推荐模块 ​

type 为 editorial_recommendations 的表示搜索结果页中的编辑推荐区域。

字段类型说明
itemsarray编辑推荐模块的商品列表。
items[].typestring固定为 amazon_serp_element。
items[].xpathstring商品的 XPath 路径。

余商品属性请参见“商品字段”。

top_rated_from_our_brands：高评分自有品牌模块 ​

type 为 top_rated_from_our_brands 的表示高评分自有品牌区域。该模块中的商品来自 Amazon 自有品牌，通常在站展示。

字段类型说明
itemsarray该模块的商品列表。
items[].typestring商品类型，通常为 amazon_serp_element。
items[].xpathstring商品的 XPath 路径。

余商品属性请参见“商品字段”。

type 为 related_searches 的表示搜索推荐区域。

字段类型说明
itemsarray搜索项列表。
items[].typestring固定为 related_searches_element。
items[].titlestring搜索词或推荐项标题。
items[].urlstring对应搜索或商品页面 URL。
items[].image_altstring图片 alt 属性文本。
items[].image_urlstring搜索项图片 URL。

响应示例 ​

json
{
  "version": "0.1.20200923",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1189 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "04170913-0696-0179-0000-707d6a06f64b",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1023 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "/v3/merchant/amazon/products/task_get/advanced/04170913-0696-0179-0000-707d6a06f64b"
      ],
      "data": {
        "se_type": "organic",
        "se": "amazon",
        "api": "merchant",
        "function": "products",
        "priority": 2,
        "language_code": "en_US",
        "location_code": 2840,
        "keyword": "gaming keyboard",
        "device": "desktop",
        "os": "windows"
      },
      "result": [
        {
          "keyword": "gaming keyboard",
          "type": "organic",
          "se_domain": "amazon.com",
          "location_code": 2840,
          "language_code": "en_US",
          "check_url": "https://www.amazon.com/s?k=gaming+keyboard",
          "datetime": "2025-02-05 12:57:46 +00:00",
          "spell": null,
          "item_types": [
            "amazon_paid",
            "amazon_serp",
            "editorial_recommendations",
            "related_searches"
          ],
          "se_results_count": 50544,
          "categories": [],
          "items_count": 3,
          "items": [
            {
              "type": "amazon_paid",
              "rank_group": 1,
              "rank_absolute": 1,
              "xpath": "/html/body/div/div/div/div/div/span/div/div",
              "domain": "www.amazon.com",
              "title": "REGAL Premiere Movie Ticket – Digital Ticket",
              "url": "https://www.amazon.com/dp/B0F3RQY7CH",
              "image_url": "https://m.media-amazon.com/images/I/61lcBjAMlLL._AC_UY218_.jpg",
              "bought_past_month": null,
              "price_from": 12.5,
              "price_to": null,
              "currency": "USD",
              "special_offers": null,
              "data_asin": "B0F3RQY7CH",
              "rating": {
                "type": "rating_element",
                "position": "left",
                "rating_type": "Max5",
                "value": 4.3,
                "votes_count": 25,
                "rating_max": 5
              },
              "is_amazon_choice": false,
              "is_best_seller": false,
              "delivery_info": null,
              "labels": null
            },
            {
              "type": "amazon_serp",
              "rank_group": 1,
              "rank_absolute": 3,
              "xpath": "/html/body/div/div/div/div/div/span/div/div",
              "domain": "www.amazon.com",
              "title": "Redragon S101 Wired Gaming Keyboard and Mouse Combo",
              "url": "https://www.amazon.com/dp/B00NLZUM36",
              "image_url": "https://m.media-amazon.com/images/I/71kr3WAj1FL._AC_UY218_.jpg",
              "bought_past_month": 100,
              "price_from": 36.98,
              "price_to": null,
              "currency": "USD",
              "special_offers": null,
              "data_asin": "B00NLZUM36",
              "rating": {
                "type": "rating_element",
                "position": "left",
                "rating_type": "Max5",
                "value": 4.5,
                "votes_count": 12162,
                "rating_max": 5
              },
              "is_amazon_choice": false,
              "is_best_seller": true,
              "delivery_info": {
                "delivery_message": "Get it as soon as Tue, Sep 28 FREE Shipping by Amazon",
                "delivery_price": null
              },
              "labels": null
            },
            {
              "type": "editorial_recommendations",
              "rank_group": 1,
              "rank_absolute": 5,
              "position": "left",
              "xpath": "/html/body/div/div/div/div/div/span/div/div",
              "items": [
                {
                  "type": "amazon_serp_element",
                  "xpath": "/html/body/div/div/div/div/div/span/div/div/ol/li",
                  "domain": "www.amazon.com",
                  "title": "NPET K10 Gaming Keyboard USB Wired",
                  "url": "https://www.amazon.com/dp/B01ALLT2W4",
                  "image_url": "https://m.media-amazon.com/images/I/61w0BypBzrL._AC_UL320_.jpg",
                  "bought_past_month": 100,
                  "price_from": 21.99,
                  "price_to": null,
                  "currency": "USD",
                  "special_offers": null,
                  "data_asin": "B01ALLT2W4",
                  "rating": {
                    "type": "rating_element",
                    "position": "left",
                    "rating_type": "Max5",
                    "value": 4.5,
                    "votes_count": 4223,
                    "rating_max": 5
                  },
                  "is_amazon_choice": false,
                  "is_best_seller": false,
                  "delivery_info": {
                    "delivery_message": "Fast Delivery To Your Door",
                    "delivery_price": null
                  },
                  "labels": null
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

使用说明 ​

  • 请通过商品搜索任务提交接口创建任务，再使用创建任务时返回的 id 查询结果。
  • 若任务尚未完成，建议调用 /v3/merchant/amazon/products/tasks_ready 获取已完成任务列表，随后使用的高级结果地址或任务 ID 拉取结果。
  • status_code 为 20000 表示接口请求成功；还应检查 tasks[].status_code，确认任务执行成功。
  • 当 tasks[].status_code 大于或等于 40000 时，应根据 status_message 记录错误并执行重试、告警或降级处理。
  • 可使用沙箱接口查看完整字段结构，沙箱请求不计费：
text
https://sandbox.seermartech.cn/v3/merchant/amazon/products/task_get/advanced/00000000-0000-0000-0000-000000000000

实用场景 ​

  • 监控商品排名：按目标定期获取自然结果与推广结果的绝对排名，追踪自有 ASIN 及竞品的变化。
  • 识别竞品广告投放：筛选 amazon_paid 类型结果，发现特定下持续投放的竞品商品，为广告竞价和选词提供依据。
  • 评估商品竞争强度：结合价格、评分、评价数、月购买量和 Best Seller 标签，量化细分品类中的头部竞品门槛。
  • 挖掘搜索词：提取 related_searches 模块中的推荐词，扩展站 SEO、广告投放和商品标题优化的长尾库。
  • 优化履约与定价策略：分析竞品文案、运费、优惠及价格区间，制定更竞争力的和促销方案。

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

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