Amazon 商品实时 HTML 结果接口

POST /v3/merchant/amazon/products/live/html

接口说明

该接口用于实时获取 Amazon 商品搜索结果页的 HTML 原始。

• 请求方式：POST
• 接口路径：/v3/merchant/amazon/products/live/html
• 完整地址：https://api.seermartech.cn/v3/merchant/amazon/products/live/html

该接口返回 JSON 响应 result.items[].html含抓取到的页面 HTML。

计费与调用限制

• 在成功创建任务时计费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 参考价约 ¥0.0800 / 次
• 所有 POST 数据使用 JSON（UTF-8）
• 请求体格式为 JSON 数组：[{ ... }]
• 每分钟最多可发送 2000 次 API 调用
• 每次 Live 请求 只能 1 个任务

请求参数

以下为任务对象可用字段说明。

字段名	类型	说明
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 时填。搜索地区完整名称。使用该字段时，无需再传 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"。latitude 和 longitude 最多 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 对象中。

响应结构

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

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码。完整错误码请参考 /v3/appendix/errors
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	请求中的语言代码
datetime	string	结果获取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
items_count	integer	items 数组中的结果数量
items	array	HTML 页面及数据

items[] 字段

字段名	类型	说明
page	integer	返回的 HTML 页码序号
date	string	HTML 页面抓取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
html	string	页面 HTML 原文

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/merchant/amazon/products/live/html" \
--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/html"
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 fetchAmazonProductsHtml {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/merchant/amazon/products/live/html",
 [
 {
 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);
}

fetchAmazonProductsHtml;

响应示例

{
 "version": "0.1.20260520",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "15.1520 sec.",
 "cost": 0.005,
 "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": [
 {
 }
 ]
 }
 ]
}

错误处理

• 顶层 status_code 表示整个请求的执行状态
• tasks[].status_code 表示单个任务的执行状态
• 建议同时处理顶层状态与任务状态，确保在批处理、参数错误、额不足或数据抓取异常时能够正确降级
• 完整错误码与状态说明请参考 /v3/appendix/errors

使用建议

1. 优使用结构化参数 建议优传 keyword + location + language，而不是直接传 url，这样稳定性更高。

2. 合理控制抓取范围 若只需首屏或前几页结果，可使用较小的 depth 和 max_crawl_pages，以控制成本与响应时间。

3. 价格与排序优级 如果已经使用 price_min、price_max 或 sort_by，不要再依赖 search_param 中的同类控制项，因为会被忽略。

4. 适合页面级解析场景 该接口返回的是 HTML 原文，更适合需要自定义解析规则、提取页面模块、复刻页面结构或做 DOM 级分析的场景。

实用场景

• 抓取商品搜索结果页原始 HTML：用于自建解析器，提取标题、价格、评分、评论数、徽章、广告位等细粒度信息。
• 监控竞品在 Amazon 搜索中的展示变化：按定期抓取 HTML，对比排序、促销标签和页面模块变化，竞品监测。
• 验证特定筛选与排序条件下的页面表现：结合价格区间、部门、排序规则抓取结果页，检查不同策略下商品差异。
• 构建类目级搜索样本库：按 department 批量获取不同品类的搜索结果页面，为选品分析和类目研究提供基础数据。
• 复核结构化结果接口未覆盖的页面：当需要识别目标页面中的特殊组件、实验样式或动态区块时，可直接基于 HTML 做补分析。