Amazon 商品搜索任务提交

接口说明

该接口用于提交 Amazon 商品搜索任务。你可以按指定的（商品名称）、地区和语言抓取 Amazon 商品列表结果。

请求方法：POST
接口地址：https://api.seermartech.cn/v3/merchant/amazon/products/task_post

创建任务后，系统会返回任务 ID。你可以通过该 id 查询任务结果；如果在创建任务时指定了 postback_url 或 pingback_url，本平台也可以在任务完成后主动回调你的服务。

计费说明

该接口在创建任务时计费。

实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
响应中的 cost 为原始计费金额
按文档示例，参考价约 ¥0.0480 / 次

优级与附加计费

当 priority=2 时，表示高优级执行，通常会产生额外费用。

深度与附加计费

depth 默认值为 100，最大值为 700。系统通常按每 100 条结果为一个计费单处理；当 depth > 100 且搜索引擎返回 100 条结果时，可能产生额外费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

所有 POST 数据使用 UTF-8 编码的 JSON 格式。请求体为 JSON 数组：[{ ... }]

速率与批量限制

每分钟最多 2000 次 API 调用
单次 POST 请求最多 100 个任务 -过 100 个任务时，出部分会返回错误 40006

回调说明

你可以通过以下两种方式在任务完成后接收通知或结果：

pingback_url：任务完成后，本平台向你指定地址发送 GET 通知
postback_url：任务完成后，本平台向你指定地址发送结果的 POST 请求，数据为 gzip 压缩格式

###时说明如果你的服务器在 10 秒未响应，连接会因时中止，任务将被转移至“Tasks Ready”列表，后续可自行获取结果。错误码和错误信息取决于你的服务器。

请求参数

字段名	类型	说明
`keyword`	string	填。搜索，即商品名称。最大 `700` 个字符。字段中的 `%##` 会被解码，字符 `+` 会被解码为空格。如果中需要保留 `%`，请写为 `%25`。
`url`	string	可选。搜索请求的直链 URL。系统会自动解析为所需参数。此方式处理难度较高，且要求 URL 中已准确语言和地区信息，通常不建议使用。示例：`https://www.amazon.com/s/?field-keywords=shoes&language=en_US`
`priority`	integer	可选。任务优级。`1` = 普通优级（默认），`2` = 高优级。高优级会额外计费。
`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 可能带来额外费用。
`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	可选。附加搜索参数，可用于价格和排序控制。示例：`&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` 对象中会返回该值。
`postback_url`	string	可选。任务完成后，系统会将结果以 POST 方式发送到该地址，数据为 `gzip` 压缩格式。支持在 URL 中使用 `$id` 和 `$tag` 变量。示例：`http://your-server.com/postbackscript?id=$id`
`postback_data`	string	指定 `postback_url` 时填。表示发送到你服务端的数据类型。可选值：`advanced`、`html`
`pingback_url`	string	可选。任务完成后，系统会向该地址发起 GET 通知。支持在 URL 中使用 `$id` 和 `$tag` 变量。示例：`http://your-server.com/pingscript?id=$id&tag=$tag`

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/merchant/amazon/products/task_post" \
--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/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

data = [
 {
 "location_name": "United States",
 "language_name": "English (United States)",
 "keyword": "shoes"
 },
 {
 "location_name": "United States",
 "language_name": "English (United States)",
 "keyword": "shoes",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "United States",
 "language_name": "English (United States)",
 "keyword": "shoes",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

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

TypeScript

typescript

import axios from "axios";

const postArray = [
 {
 location_name: "United States",
 language_name: "English",
 keyword: encodeURI("shows"),
 priority: 2,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/merchant/amazon/products/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.log(error);
 });

响应说明

接口返回 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 / null	任务提交接口中通常为 `null`，结果需通过任务结果接口获取

响应示例

json

{
 "version": "0.1.20200416",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1429 sec.",
 "cost": 0.003,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "merchant",
 "function": "products",
 "se": "amazon",
 "language_code": "en_US",
 "location_code": 2840,
 "keyword": "shoes",
 "priority": 2,
 "se_type": "organic",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码与错误处理

20000：请求成功
40006：单次 POST 中任务数 100

建议你在接时建立完善的异常处理机制，统一处理：

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

完整错误码体系可参考 /v3/appendix/errors。

使用建议

优使用 keyword + location + language 的组合方式创建任务，稳定性更高。
除非你已经掌握完整的 Amazon 搜索 URL 结构，否则不建议优使用 url 字段。
如需价格区间或排序控制，建议优使用结构化字段 price_min、price_max、sort_by， search_param 被覆盖。
若需要异步批量处理结果，建议 postback_url 或 pingback_url。
大批量任务提交时，请控制单次请求不 100 个任务。

实用场景

监控商品：按抓取 Amazon 商品列表，观察目标产品或竞品在不同国家与语言下的展示。
筛选价格带商品：结合 price_min、price_max 抓取指定价位商品，分析目标市场的价格分布与竞争强度。
跟踪类目竞争格局：通过 department 限定商品部门，识别细分类目中的主要竞品和热门产品。
对比排序策略影响：切换 sort_by 参数，查看性、价格、评论、新品等不同排序下的商品分布，运营策略制定。
构建异步采集流程：使用 pingback_url 或 postback_url 在任务完成后自动接收通知或结果，提升批量监控与报表生成效率。

Amazon 商品搜索任务提交 ​

接口说明 ​

计费说明 ​

优级与附加计费 ​

深度与附加计费 ​

请求格式 ​

速率与批量限制 ​

回调说明 ​

请求参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应说明 ​

顶层字段 ​

tasks 数组字段 ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​