亚马逊产品实时高级结果

POST /v3/merchant/amazon/products/live/advanced

接口说明

POST https://api.seermartech.cn/v3/merchant/amazon/products/live/advanced

本接口根据指定的、地区和语言，实时获取亚马逊产品搜索结果，并返回自然商品、付费商品、编辑推荐、品牌精选、搜索等结果模块。

请求体使用 UTF-8 编码的 JSON 数组格式。平台限流以认证说明中的 30/60/120 次/分钟规则为准。

计费说明

提交任务时计费。默认每个最多 100 条结果的 SERP 计费一次；当 depth过 100 且返回更多结果时，可能产生额外费用。

参考价约 ¥0.0238 / 次（按示例中的 0.0033 美折算供参考）。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

请求体示例：

json

[
  {
    "keyword": "shoes",
    "location_name": "United States",
    "language_name": "English (United States)"
  }
]

参数	类型	填	说明
`keyword`	string	是	搜索，通常为产品名称，最长 700 个字符。所有 `%##` 编码会被解码，字符 `+` 会被解码为空格。如中需要使用 `%`，请写作 `%25`。
`url`	string	否	搜索请求的完整 URL。接口会从 URL 中解析参数。该方式处理复杂，且 URL 中准确的语言和地区信息，通常不建议使用。示例：`https://www.amazon.com/s/?field-keywords=shoes&language=en_US`
`location_name`	string	条件填	搜索地区完整名称。未指定 `location_code` 或 `location_coordinate` 时填。使用此参数后，不要同时传另外两个地区参数。可通过 `/v3/merchant/amazon/locations` 获取可用值。示例：`HA1,England,United Kingdom`
`location_code`	integer	条件填	搜索地区编码。未指定 `location_name` 或 `location_coordinate` 时填。使用此参数后，不要同时传另外两个地区参数。示例：`9045969`
`location_coordinate`	string	条件填	地区 GPS 坐标，格式为 `latitude,longitude,radius`。经纬度最多 7 位小数，`radius` 最小值为 `199.9`。示例：`53.476225,-2.243572,200`
`language_name`	string	条件填	搜索语言完整名称。未指定 `language_code` 时填。使用此参数后，不要同时传 `language_code`。可通过 `/v3/merchant/amazon/languages` 获取可用值。
`language_code`	string	条件填	搜索语言编码。未指定 `language_name` 时填。使用此参数后，不要同时传 `language_name`。示例：`en_GB`
`se_domain`	string	否	搜索域名。接口会根据地区和语言自动选择域名，也可以手动指定，例如 `amazon.com`、`amazon.co.uk`、`amazon.fr`。
`depth`	integer	否	解析深度，即最多获取的结果数量。默认值为 `100`，最大值为 `700`。 100 可能产生额外费用。
`max_crawl_pages`	integer	否	最多抓取的搜索结果页数，最大值为 `7`。该参数与 `depth`合使用。
`department`	string	否	产品部门。支持：`Arts & Crafts`、`Automotive`、`Baby`、`Beauty & Personal Care`、`Books`、`Computers`、`Digital Music`、`Electronics`、`Kindle Store`、`Prime Video`、`Women's Fashion`、`Men's Fashion`、`Girls' Fashion`、`Boys' Fashion`、`Deals`、`Health & Household`、`Home & Kitchen`、`Industrial & Scientific`、`Luggage`、`Movies & TV`、`Music, CDs & Vinyl`、`Pet Supplies`、`Software`、`Sports & Outdoors`、`Tools & Home Improvement`、`Toys & Games`、`Video Games`。
`search_param`	string	否	搜索附加参数，可传亚马逊搜索 URL 参数。例如：`&low-price=52`、`&high-price=45`、`&sort=relevancerank`、`&sort=featured-rank`、`&sort=price-asc-rank`、`&sort=price-desc-rank`、`&sort=review-rank`、`&sort=date-desc-rank`。如果同时传 `price_min`、`price_max` 或 `sort_by`，该参数将被忽略。
`price_min`	integer	否	返回产品的最低价格。示例：`5`。传后忽略 `search_param`。
`price_max`	integer	否	返回产品的最高价格。示例：`100`。传后忽略 `search_param`。
`sort_by`	string	否	结果排序方式。支持：`relevance`、`price_low_to_high`、`price_high_to_low`、`featured`、`avg_customer_review`、`newest_arrival`。传后忽略 `search_param`。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样返回在响应任务的 `data` 对象中，便于请求与结果。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/merchant/amazon/products/live/advanced" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_name": "United States",
      "language_name": "English (United States)",
      "keyword": "shoes"
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/merchant/amazon/products/live/advanced"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

# 每次调用只能提交一个任务
payload = [
    {
        "location_name": "United States",
        "language_name": "English (United States)",
        "keyword": "shoes",
    }
]

response = requests.post(url, headers=headers, json=payload)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，错误码：%s，错误信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/merchant/amazon/products/live/advanced",
  [
    {
      location_name: "United States",
      language_name: "English (United States)",
      keyword: "shoes",
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

console.log(response.data);

响应结构

接口返回 JSON 数据，核心结构如下：

json

{
  "version": "0.1.20260520",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "17.2698 sec.",
  "cost": 0.0238,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "17.2698 sec.",
      "cost": 0.0238,
      "result_count": 1,
      "data": {
        "api": "merchant",
        "function": "products",
        "se": "amazon",
        "language_code": "en_US",
        "location_code": 2840,
        "keyword": "shoes",
        "se_type": "products",
        "device": "desktop",
        "os": "windows"
      },
      "result": [
        {
          "se_results_count": 69070,
          "categories": null,
          "items_count": 2,
          "items": [
            {
              "type": "amazon_serp",
              "rank_group": 1,
              "rank_absolute": 1,
              "domain": "www.amazon.com",
              "title": "示例商品名称",
              "url": "https://www.amazon.com/example-product/dp/B000000000",
              "image_url": "https://m.media-amazon.com/images/example.jpg",
              "bought_past_month": 1000,
              "price_from": 60.57,
              "price_to": null,
              "currency": "USD",
              "special_offers": null,
              "data_asin": "B000000000",
              "rating": {
                "type": "rating_element",
                "position": "left",
                "rating_type": "Max5",
                "value": 4.5,
                "votes_count": 13200,
                "rating_max": 5
              },
              "is_amazon_choice": true,
              "is_best_seller": false,
              "delivery_info": {
                "delivery_message": "FREE delivery",
                "delivery_price": null
              },
              "labels": null
            }
          ]
        }
      ]
    }
  ]
}

响应字段

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求总体状态码。完整错误码参见 `/v3/appendix/errors`。
`status_message`	string	请求总体状态信息。
`time`	string	执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数。
`tasks`	array	任务结果数组。

任务字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码，通常在 `10000` 至 `60000` 范围。
`status_message`	string	任务状态信息。
`time`	string	任务执行耗时。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求 URL 路径信息。
`data`	object	请求中提交的参数，以及接口补的解析参数。
`result`	array	搜索结果数组。

搜索结果字段

字段	类型	说明
`keyword`	string	请求中的。返回时已解码 `%##`，字符 `+` 会解码为空格。
`type`	string	搜索结果类型。
`se_domain`	string	搜索域名。
`location_code`	integer	地区编码。
`language_code`	string	语言编码。
`check_url`	string	亚马逊结果页的直接 URL，可用于核验结果准确性。
`datetime`	string	结果获取时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`spell`	object	搜索引擎自动纠错信息。没有纠错时通常为空。
`spell.keyword`	string	自动纠错后的，结果基于该返回。
`spell.type`	string	纠错类型：`did_you_mean`、`showing_results_for`、`no_results_found_for`、`including_results_for`。
`item_types`	array	SERP 中出现的结果类型：`amazon_serp`、`amazon_paid`、`editorial_recommendations`、`top_rated_from_our_brands`、`related_searches`。
`se_results_count`	integer	搜索引擎结果总数。
`categories`	array	产品部门及子分类。
`items_count`	integer	`items` 数组中的结果数量。
`items`	array	产品及 SERP素数组。

SERP素字段

通用商品字段

以下字段可能出现在自然商品、付费商品、编辑推荐和品牌精选商品中：

字段	类型	说明
`type`	string	素类型，例如 `amazon_serp`、`amazon_paid`。
`rank_group`	integer	同类型中的组排名。不同类型之间不会连续计该字段。
`rank_absolute`	integer	在整个 SERP 中的绝对排名。
`position`	string	素在 SERP 中的对齐位置，可能为 `left` 或 `right`。
`xpath`	string	素在页面中的 XPath。
`domain`	string	亚马逊域名。
`title`	string	产品标题。
`url`	string	产品页 URL。
`image_url`	string	搜索结果中展示的产品图片 URL。
`bought_past_month`	integer	过去一个月的购买数量，可能为 `null`。
`price_from`	float	产品常规起始价格。
`price_to`	float	产品价格区间上限。
`currency`	string	ISO 货币编码，例如 `USD`。
`special_offers`	array	特殊优惠信息优惠券和订省优惠等。
`data_asin`	string	亚马逊产品唯一标识。该值由亚马逊动态分，不存在固定枚举列表。示例：`B07G82D89J`。
`rating`	object	产品评分信息。
`rating.type`	string	固定为 `rating_element`。
`rating.position`	string	评分在 SERP 中的对齐位置：`left` 或 `right`。
`rating.rating_type`	string	评分类型：`Max5`、`Percents` 或 `CustomMax`。
`rating.value`	float	评分值。
`rating.votes_count`	integer	评价数量。
`rating.rating_max`	integer	评分类型对应的最大值。
`is_amazon_choice`	boolean	是否带有“Amazon's Choice”标签。
`is_best_seller`	boolean	是否带有“Best Seller”标签。
`delivery_info`	object	送信息说明和费用。
`delivery_info.delivery_message`	string	卖家展示的说明。
`delivery_info.delivery_price`	object/null	根据请求地区计算的价格。时为 `null`。
`delivery_info.delivery_price.current`	float	当前价格。
`delivery_info.delivery_price.regular`	float	未折扣的常规价格。
`delivery_info.delivery_price.max_value`	float	未折扣价格区间的最大值。
`delivery_info.delivery_price.currency`	string	送价格的 ISO 货币编码。
`delivery_info.delivery_price.is_price_range`	boolean	是否为价格区间。
`delivery_info.delivery_price.displayed_price`	string	商品列表中原样展示的价格文本。
`labels`	array/null	产品标签信息。没有标签时为 `null`。
`labels[].type`	string	固定为 `amazon_label_element`。
`labels[].title`	string	标签标题，例如 `Audiobook`。
`labels[].url`	string	标签产品链接 URL。
`labels[].domain`	string/null	标签链接域名；亚马逊场景下通常为 `null`。

编辑推荐

editorial_recommendations_element 表示编辑推荐模块，字段：

type：固定为 editorial_recommendations
rank_group：同类型中的组排名
rank_absolute：SERP 绝对排名
position：对齐位置，left 或 right
xpath：页面 XPath
items：该模块中的商品数组

items 中的商品使用上述通用商品字段，且商品的 type 通常为 amazon_serp_element。

自有品牌精选

top_rated_from_our_brands_element 表示“Top rated from our brands”模块，字段：

type：固定为 top_rated_from_our_brands
rank_group：同类型中的组排名
rank_absolute：SERP 绝对排名
xpath：页面 XPath
items：该模块中的产品数组

该模块中的产品通常来自亚马逊自有品牌，商品类型为 amazon_serp_element。

付费商品

amazon_paid_element 表示付费商品结果，字段：

type：固定为 amazon_paid
rank_group：同类型中的组排名
rank_absolute：SERP 绝对排名
xpath：页面 XPath
字段：使用通用商品字段标题、URL、价格、ASIN、评分、标签和信息等

搜索

related_searches_element 表示搜索模块，字段：

type：固定为 related_searches
rank_group：同类型中的组排名
rank_absolute：SERP 绝对排名
xpath：页面 XPath
items：搜索项数组

搜索项字段：

字段	类型	说明
`type`	string	素类型，通常为 `related_searches_element`。
`title`	string	搜索或产品标题。
`url`	string	链接 URL。
`image_alt`	string	产品图片的替代文本。
`image_url`	string	产品图片 URL。

错误处理

建议同时检查以下状态字段：

顶层 status_code
顶层 status_message
任务级 tasks[].status_code
任务级 tasks[].status_message
tasks_error

当状态码不为 20000 时，应记录任务 ID、状态码和错误信息，并根据业务需要执行重试或异常告警。完整错误码参见 /v3/appendix/errors。

实用场景

监控核心的商品排名，跟踪自然商品和付费商品在不同国家、语言及地区的排名变化，评估市场度。
比较竞品价格与优惠策略，结合 price_from、price_to、special_offers 和费用，识别价格竞争区间。
筛选高评价及销商品，利用 rating、votes_count、is_amazon_choice 和 is_best_seller 发现重点竞品和潜在选品。
分析不同部门的搜索结果结构，通过 department、item_types 和 categories 研究类目分布及 SERP 展示模块。
发现用户搜索需求，读取 related_searches_element 中的搜索词，为产品标题、描述和 SEO 提供扩展方向。

亚马逊产品实时高级结果 ​

接口说明 ​

计费说明 ​

请求参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

响应字段 ​

顶层字段 ​

任务字段 ​

搜索结果字段 ​

SERP素字段 ​

通用商品字段 ​

编辑推荐 ​

自有品牌精选 ​

付费商品 ​

搜索 ​

错误处理 ​

实用场景 ​