Amazon 商品实时搜索结果（高级版）

接口说明

/v3/merchant/amazon/products/live/advanced 用于根据指定的（商品名称）、地域和语言，实时获取 Amazon 商品搜索结果页中的商品列表及扩展。

与基础版相比，高级版会返回更丰富的结果结构，除普通自然商品外，还可能广告位、编辑推荐、搜索、品牌专区等 SERP素，适合做更细粒度的商品搜索分析。

请求方式：

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

计费与调用限制

• 在任务成功提交时计费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 参考价约 ¥0.0528 / 次
• 每分钟最多可发送 2000 次 API 调用
• 单次 POST 请求最多 100 个任务
• 如果单次请求中任务数 100，出部分会返回错误 40006

请求格式

所有 POST 数据使用 JSON（UTF-8 编码）提交。

根据本平台容规范，POST 请求体应为 JSON 数组：

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

回调说明

你可以通过任务唯一标识 id 获取结果。 如果在创建任务时设置了 postback_url 或 pingback_url，本平台也可以在结果就绪后主动推送。

注意事项：

• 你的服务端需要在 10 秒响应
• 若时未响应，连接会被中止
• 该任务会被转对应的就绪任务列表
• 返回的错误码和错误信息取决于你的服务端

请求参数

参数名	类型	说明
keyword	string	填。搜索，即商品名称。最多 700 个字符。 %## 会被解码，字符 + 会被解码为空格。如果中需要保留 %，请写为 %25。
url	string	可选。搜索结果页的直达 URL。本接口会自动解析出所需参数。但这种方式处理难度更高，且要求 URL 中准确语言和地域信息，通常不推荐使用。示例：https://www.amazon.com/s/?field-keywords=shoes&language=en_US
location_name	string	当未提供 location_code 或 location_coordinate 时填。搜索地域完整名称。使用该字段时，无需再传 location_code 或 location_coordinate。可通过 /v3/merchant/amazon/locations 获取可用地域列表。示例：HA1,England,United Kingdom
location_code	integer	当未提供 location_name 或 location_coordinate 时填。搜索地域编码。使用该字段时，无需再传 location_name 或 location_coordinate。可通过 /v3/merchant/amazon/locations 获取可用地域列表。示例：9045969
location_coordinate	string	当未提供 location_name 或 location_code 时填。GPS 坐标，格式为 "latitude,longitude,radius"。纬度和经度最多 7 位小数；radius 最小值为 199.9。示例：53.476225,-2.243572,200
language_name	string	当未提供 language_code 时填。搜索语言完整名称。使用该字段时，无需再传 language_code。可通过 /v3/merchant/amazon/languages 获取可用语言列表。示例：English (United Kingdom)
language_code	string	当未提供 language_name 时填。搜索语言编码。使用该字段时，无需再传 language_name。可通过 /v3/merchant/amazon/languages 获取可用语言列表。示例：en_GB
se_domain	string	可选。搜索域名。默认会根据地域和语言自动选择，也可以手动指定，如 amazon.com、amazon.co.uk、amazon.fr。
depth	integer	可选。抓取结果深度，即返回的商品数量。默认 100，最大 700。每 100 条结果按一个 SERP 单位计费；当 depth过 100 且搜索引擎返回 100 条结果时，可能产生额外费用。
max_crawl_pages	integer	可选。最多抓取的结果页数，最大值 7。该参数与 depth 互补决定最终抓取范围。
department	string	可选。指定 Amazon 商品部门。支持以下值："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	可选。附加搜索参数，可直接传 Amazon 搜索 URL 参数。例如：&low-price=52 表示查找价格高于 52 的商品；&high-price=45 表示查找价格低于 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，则 search_param 会被忽略。
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。示例："relevance"。如果传该参数，search_param 会被忽略。
tag	string	可选。用户自定义任务标识，最多 255 个字符。可用于请求结果，响应中的 data 对象会原样返回该值。

请求示例

cURL

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

import requests

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

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

TypeScript

import axios from "axios";

async function fetchAmazonProductsAdvanced {
 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);
}

fetchAmazonProductsAdvanced;

响应结构

接口返回 JSON 数据，顶层 tasks 数组，每个任务对应结果。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码
status_message	string	通用提示信息
time	string	执行耗时，单位秒
cost	float	所有任务总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数量
tasks	array	任务结果数组

tasks[] 字段

字段	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000 - 60000
status_message	string	任务提示信息
time	string	任务执行耗时
cost	float	单任务费用，单位 USD
result_count	integer	result 数组数量
path	array	URL 路径
data	object	原样返回提交时的请求参数
result	array	获取结果数组

result[] 字段

字段	类型	说明
keyword	string	请求中的。返回时 %## 和 + 会被解码
type	string	搜索引擎类型
se_domain	string	搜索域名
location_code	integer	地域编码
language_code	string	语言编码
check_url	string	对应 Amazon 搜索结果页直达地址，可用于核验结果
datetime	string	结果抓取时间，UTC 格式，如 2019-11-15 12:57:46 +00:00
spell	object	搜索引擎自动纠错信息
item_types	array	当前 SERP 中出现的结果类型
se_results_count	integer	搜索结果总量
categories	array	商品部门与子类目
items_count	integer	items 数组中的数量
items	array	结果明细

spell 字段

当平台对进行了自动纠错时，会返回该对象。

字段	类型	说明
keyword	string	自动纠错后的
type	string	纠错类型：did_you_mean、showing_results_for、no_results_found_for、including_results_for

item_types 可选值

item_types 可能以下类型：

• amazon_serp
• amazon_paid
• editorial_recommendations
• top_rated_from_our_brands
• related_searches

items 中的结果类型说明

高级版的 items 数组可能混合返回多种。以下为主要结构。

1）普通自然商品：amazon_serp

字段	类型	说明
type	string	固定为 amazon_serp
rank_group	integer	同类型结果中的组排名
rank_absolute	integer	在整个 SERP 中的绝对排名
xpath	string	素 XPath
domain	string	Amazon 域名
title	string	商品标题
url	string	商品页 URL
image_url	string	商品图片 URL
bought_past_month	integer	过去一个月购买量
price_from	float	商品常规价格
price_to	float	商品价格区间上限
currency	string	币种，ISO 4217 格式，如 USD
special_offers	array	优惠信息，如优惠券、订省等
data_asin	string	Amazon 商品唯一标识
rating	object	商品评分信息
is_amazon_choice	boolean	是否带有 “Amazon's choice” 标记
is_best_seller	boolean	是否带有 “Best Seller” 标记
delivery_info	object	送信息
labels	array	商品标签信息；无标签时为 null

rating 字段

字段	类型	说明
type	string	固定为 rating_element
position	string	素对齐位置：left、right
rating_type	string	评分类型：Max5、Percents、CustomMax
value	string/float	评分值
votes_count	integer	评价数量
rating_max	string/float	当前评分制的最大值

delivery_info 字段

字段	类型	说明
delivery_message	string	送文案
delivery_price	object/null	送价格信息；若运费则为 null

delivery_price 字段

字段	类型	说明
current	float	当前价
regular	float	原始价
max_value	float	未折扣价上限
currency	string	币种，ISO 4217 格式
is_price_range	boolean	是否为价格区间
displayed_price	string	页面展示的价格文本

labels 字段

字段	类型	说明
type	string	固定为 amazon_label_element
title	string	标签标题，如 "Audiobook"
url	string	标签商品链接
domain	string	标签链接中的域名；对 Amazon部标签通常为 null

2）广告商品：amazon_paid

广告商品字段与 amazon_serp 基本一致，区别在于：

字段	类型	说明
type	string	固定为 amazon_paid

余如 rank_group、rank_absolute、title、price_from、rating、delivery_info、labels 等字段含义与自然商品相同。

3）编辑推荐模块：editorial_recommendations

该表示 SERP 中的编辑推荐区域。

字段	类型	说明
type	string	固定为 editorial_recommendations
rank_group	integer	同类型中的排名
rank_absolute	integer	整体绝对排名
position	string	素位置：left、right
xpath	string	素 XPath
items	array	模块中的商品项

items商品通常为 amazon_serp_element，字段：

• type
• xpath
• domain
• title
• url
• image_url
• bought_past_month
• price_from
• price_to
• currency
• special_offers
• data_asin
• rating
• is_amazon_choice
• is_best_seller
• delivery_info
• labels

4）品牌高评分模块：top_rated_from_our_brands

表示 “Top rated from our brands” 等品牌专区。

字段	类型	说明
type	string	固定为 top_rated_from_our_brands
rank_group	integer	同类型中的排名
rank_absolute	integer	整体绝对排名
xpath	string	素 XPath
items	array	该专区中的商品项

items 中通常 amazon_serp_element 类型商品，字段定义与普通商品基本一致。

5）搜索：related_searches

表示搜索结果页中的搜索模块。

字段	类型	说明
type	string	固定为 related_searches
rank_group	integer	同类型中的排名
rank_absolute	integer	整体绝对排名
xpath	string	素 XPath
items	array	搜索项列表

items 中的每个通常：

字段	类型	说明
type	string	固定为 related_searches_element
title	string	搜索标题
url	string	对应链接
image_alt	string	图片 alt 文本
image_url	string	图片 URL

响应示例

{
 "version": "0.1.20260520",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "17.2698 sec.",
 "cost": 0.0033,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "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": 12,
 "items": [
 {
 "type": "amazon_serp",
 "rank_group": 1,
 "rank_absolute": 1,
 "xpath": "/body/div/div/div/div/div/span/div/div",
 "domain": "www.amazon.com",
 "title": "Women’s VL Court 3.0 Sneaker",
 "url": "https://www.amazon.com/adidas-Womens-Court-Sneaker-White/dp/B0C2JXSHSK/ref=sr_1_1",
 "image_url": "https://m.media-amazon.com/images/I/613wTu5YLOL._AC_UL320_.jpg",
 "bought_past_month": 1000,
 "price_from": 60.57,
 "price_to": null,
 "currency": "USD",
 "special_offers": null,
 "data_asin": "B0C2JXSHSK",
 "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 May 30 - 31 Or fastest delivery Fri, May 29",
 "delivery_price": null
 },
 "labels": null
 },
 {
 "type": "amazon_paid",
 "rank_group": 1,
 "rank_absolute": 10,
 "xpath": "/html/body/div/div/div/div/div/span/div/div/div/div/span/div/div/div/div/div",
 "domain": "www.amazon.com",
 "title": "Reebok Futura Dash Running Mens Shoes",
 "url": "https://www.amazon.com/Reebok-Futura-Running-Shoes-Grey6/dp/B0G5BWY5XT/ref=sxin_26_sbv_search_btf",
 "image_url": "https://m.media-amazon.com/images/I/81OoE8qNigL._AC_UL640_QL65_.jpg",
 "bought_past_month": null,
 "price_from": 69.95,
 "price_to": null,
 "currency": "USD",
 "special_offers": null,
 "data_asin": "B0G5BWY5XT",
 "rating": {
 "type": "rating_element",
 "position": "left",
 "rating_type": "Max5",
 "value": 4.8,
 "votes_count": 13,
 "rating_max": 5
 },
 "is_amazon_choice": false,
 "is_best_seller": false,
 "delivery_info": {
 "delivery_message": "Prime delivery available",
 "delivery_price": null
 },
 "labels": null
 },
 {
 "type": "related_searches",
 "rank_group": 3,
 "rank_absolute": 151,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div/span/div/div/div/a",
 "items": []
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

• 顶层 status_code 表示整次请求处理状态
• tasks[].status_code 表示单个任务状态
• 建议同时处理 HTTP 状态码、顶层状态码和任务状态码
• 常见限制错误：
• 40006：单次 POST 请求中的任务数量限（ 100）

完整错误码说明可参考 /v3/appendix/errors。

使用建议

• 优使用 keyword + location + language 方式提交，不建议直接传 url
• 需要按价格和排序过滤时，优使用结构化字段：price_min、price_max、sort_by
• 若同时设置 search_param 与结构化筛选字段，以结构化字段为准
• 若需扩大结果覆盖范围，可结合 depth 与 max_crawl_pages 使用，但可能增加费用
• 对于 SERP 分析，请注意 items 中可能混合自然结果、广告结果及模块化，解析时应按 type 分流处理

实用场景

• 监控商品排名：按、地域和语言抓取商品搜索结果，跟踪自有商品或竞品在 Amazon 搜索页中的位置变化。
• 识别广告与自然位占比：区分 amazon_paid 与 amazon_serp，评估某下广告挤占自然流量的程度。
• 分析价格带竞争格局：结合 price_from、price_to、price_min、price_max，观察不同价格区间的商品密度和竞争强度。
• 提取高转化商品信号：利用评分、评论数、月购买量、Amazon Choice、Best Seller 等字段，识别高表现商品特征。
• 发现搜索需求扩展词：解析 related_searches 模块，挖掘用户在同类商品搜索中的需求，用于选品和扩展。