SeerMarTech API 文档

主题

提交 Google Shopping 商家列表任务 ​

POST /v3/merchant/google/sellers/task_post

/v3/merchant/google/sellers/task_post 用于创建 Google Shopping 商家列表采集任务。任务完成后，本接口可返回指定商品在 Google Shopping 中的前 10 个商家列表，并每个商家的商品基础价格、总价、与购买信息以及促销信息。

返回结果会受到所选地区和语言的影响，因此创建任务时正确指定定位参数与语言参数。

注意：调用本接口前，需要获取以下任一商品标识：product_id、data_docid 或 gid。这些值可通过 /v3/merchant/google/products/task_post 行查询获得。 为获得更稳定的匹效果，建议尽可能同时传 product_id、data_docid 和 gid。

接口地址 ​

POST https://api.seermartech.cn/v3/merchant/google/sellers/task_post

计费说明 ​

本接口按创建任务计费，不按获取结果计费。

  • 参考价约 ¥0.0320 / 次
  • 如使用高优级 priority=2，会产生更高费用
  • 当 get_shops_on_google=true 时，任务费用会翻倍
  • 当 depth > 10 且搜索引擎返回 10 条结果时，可能产生额外费用
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求说明 ​

  • 请求体为 UTF-8 编码的 JSON
  • POST 请求体格式为：[{ ... }]
  • 单次 POST 最多可提交 100 个任务
  • 每分钟最多可发送 2000 次 API 调用
  • 如果单次请求中任务数 100，出部分会返回错误 40006

任务结果获取方式 ​

创建任务后，可通过返回的任务 id 轮询获取结果；也可以在创建任务时设置：

  • postback_url：任务完成后，本平台会向该地址发送结果数据的 POST 请求，数据使用 gzip 压缩
  • pingback_url：任务完成后，本平台会向该地址发送通知型 GET 请求

如果您的服务端在 10 秒未响应，连接会因时被中断，任务会 /v3/merchant/google/sellers/tasks_ready/ 列表，后续可从该列表获取已完成任务。

postback_url 与 pingback_url 中支持以下变量：

  • $id：任务 ID
  • $tag：URL 编码后的任务标签

例如：

  • https://your-server.com/postbackscript?id=$id
  • https://your-server.com/postbackscript?id=$id&tag=$tag

注意：回调 URL 中的特殊字符会被 URL 编码，例如 # 会被编码为 %23。

请求参数 ​

字段名类型说明
product_idstringGoogle Shopping 商品唯一标识。若未提供 data_docid 或 gid，则为填。建议与 data_docid、gid 一并传以获得更优结果。示例：4485466949985702538
data_docidstringSERP 数据唯一标识。若未提供 product_id 或 gid，则为填。建议与 product_id、gid 一并传。示例：13071766526042404278
gidstringGoogle Shopping局商品标识。若未提供 product_id 或 data_docid，则为填。建议与 product_id、data_docid 一并传。示例：4702526954592161872
pvfstringGoogle Shopping 商品变体过滤参数，可选。通常来自商品页 URL 中的参数，用于限定颜色、尺寸、等变体。示例：Eg4iBWNvbG9yKgV3aGl0ZRISIgxwYWNrYWdlIHNpemUqAjE0EgoiBHNpemUqAnhs
priorityinteger任务优级，可选。1 = 普通优级（默认），2 = 高优级。高优级执行更快，但费用更高。
location_namestring完整地区名称。若未提供 location_code 或 location_coordinate，则为填。使用该字段时无需再传 location_code、location_coordinate。示例：London,England,United Kingdom
location_codeinteger地区代码。若未提供 location_name 或 location_coordinate，则为填。使用该字段时无需再传 location_name、location_coordinate。示例：2840
location_coordinatestringGPS 坐标定位。若未提供 location_name 或 location_code，则为填。格式：latitude,longitude,radius。latitude 与 longitude 最多 7 位小数；radius 最小值为 199.9。示例：53.476225,-2.243572,200
language_namestring语言名。若未提供 language_code，则为填。使用该字段时无需再传 language_code。示例：English
language_codestring语言代码。若未提供 language_name，则为填。使用该字段时无需再传 language_name。示例：en
depthinteger抓取深度，可选。表示从 Google Shopping SERP 抓取的结果数量。默认值：10；最大值：200。按每 10 条结果为一个计费单位，设置 10 可能产生额外费用。
se_domainstring搜索引擎域名，可选。默认会根据地区和语言自动选择，也可手动指定。示例：google.co.uk、google.com.au、google.de
get_shops_on_googleboolean是否“在 Google 上购买”的商家，可选。设为 true 时，响应中会支持直接在 Google购买的商家；同时任务费用翻倍。
additional_specificationsobject附加 URL 参数对象，可选。可通过 /v3/merchant/google/products/task_post 获取。示例：{"eto":"16157121050167572763_0"}
tagstring自定义任务标识，可选，最大长度 255。可用于业务侧追踪任务，响应中的 data 对象会原样返回该值。
postback_urlstring结果回传地址，可选。任务完成后，本平台会向该地址发送携带结果的 POST 请求。
postback_datastringpostback_url 的返回数据类型，可选。当前可用值：advanced
pingback_urlstring完成通知地址，可选。任务完成后，本平台会向该地址发送 GET 通知请求。

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/merchant/google/sellers/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "language_name": "English",
 "product_id": "1113158713975221117"
 },
 {
 "location_name": "United States",
 "language_name": "English",
 "product_id": "1113158713975221117",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "United States",
 "language_name": "English",
 "product_id": "1113158713975221117",
 "postback_url": "https://your-server.com/postbackscript"
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/merchant/google/sellers/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

# 请求体为 JSON 数组
payload = [
 {
 # 示例 1：最简任务提交方式
 "location_name": "United States",
 "language_name": "English",
 "product_id": "1113158713975221117"
 },
 {
 # 示例 2：高优级 + pingback 通知
 "location_name": "United States",
 "language_name": "English",
 "product_id": "1113158713975221117",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 # 示例 3：任务完成后通过 postback 直接回传结果
 "location_name": "United States",
 "language_name": "English",
 "product_id": "1113158713975221117",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)

TypeScript ​

typescript
import axios from "axios";

const payload = [
 {
 // 示例 1：最简任务提交
 location_name: "United States",
 language_name: "English",
 product_id: "1113158713975221117"
 },
 {
 // 示例 2：高优级 + pingback 回调
 location_name: "United States",
 language_name: "English",
 product_id: "1113158713975221117",
 priority: 2,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 // 示例 3：postback 直接接收结果
 location_name: "United States",
 language_name: "English",
 product_id: "1113158713975221117",
 postback_url: "https://your-server.com/postbackscript"
 }
];

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

响应说明 ​

接口返回 JSON 结构一个 tasks 数组，用于描述本次提交的任务信息。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
status_codeinteger通用状态码
status_messagestring通用状态信息
timestring请求执行耗时，单位秒
costfloat本次请求总费用，单位 USD
tasks_countintegertasks 数组中的任务总数
tasks_errorinteger返回错误的任务数量
tasksarray任务数组

tasks 数组字段 ​

字段名类型说明
idstring平台唯一任务 ID，UUID 格式
status_codeinteger任务状态码，范围通常为 10000-60000
status_messagestring任务状态信息
timestring任务处理耗时
costfloat单个任务费用，单位 USD
result_countintegerresult 数组中的数量
patharray请求路径
dataobject与提交请求时传的参数基本一致
resultarray对于任务提交接口，此处通常为 null，数据需在任务完成后获取

建议在接时对 status_code 和任务级 status_code 分别做异常处理。

响应示例 ​

json
{
 "version": "0.1.20200416",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0883 sec.",
 "cost": 0.002,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "2c4bfa9e-7b4e-4a7d-9d58-1b23456789ab",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0 sec.",
 "cost": 0.002,
 "result_count": 0,
 "path": [
 "v3",
 "merchant",
 "google",
 "sellers",
 "task_post"
 ],
 "data": {
 "api": "merchant",
 "function": "sellers",
 "se": "google",
 "language_code": "en",
 "location_code": 2840,
 "product_id": "1113158713975221117",
 "priority": 2,
 "se_type": "shops_list",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码与错误处理 ​

  • 通用成功状态通常为：20000
  • 任务创建成功通常表现为任务级状态码：20100
  • 若单次 POST 中提交的任务数 100，出部分会返回：40006

建议重点处理以下几类异常：

  1. 参数缺失或格式错误：如未传 product_id / data_docid / gid 中的任一值，或地区、语言参数不完整
  2. 任务量限：单请求 100 个任务
  3. 回调时：postback_url / pingback_url 指向的服务端 10 秒未响应
  4. 费用预估偏差：高优级、深度抓取或 get_shops_on_google=true 会提高成本

使用建议 ​

  • 若您已从商品搜索接口拿到商品标识，优同时传 product_id、data_docid、gid，可提高商家匹准确性
  • 若面向本地化价格监控，建议明确设置 location_code 或 location_coordinate
  • 若需要近实时处理，优使用 priority=2 并结合 pingback_url
  • 若需要自动库完整结果，优使用 postback_url + postback_data=advanced

实用场景 ​

  • 监控竞品售卖渠道：抓取某一商品在不同地区的前列商家列表，识别主要分销商与渠道覆盖。
  • 比对区域价格差异：按国家、城市或坐标维度采集同款商品商家报价，发现跨区域定价差与运费差异。
  • 识别可直接成交的商家：启用 get_shops_on_google，筛选支持在 Google直接购买的卖家，评估平台成交机会。
  • 追踪商品变体销售：结合 pvf 指定颜色、尺寸等变体，分析不同 SKU 在商家端的上架与报价表现。
  • 自动化回收商家结果：通过 postback_url 或 pingback_url 构建异步采集流程，降低轮询成本并加快业务库效率。

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

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