merchant/google/products/task_post

设置 Google Shopping 商品抓取任务

/v3/merchant/google/products/task_post 用于创建 Google Shopping 商品搜索任务。任务执行完成后，您可以获取指定查询词下的商品列表。

返回结果通常：

商品标题
Google Shopping 结果页中的商品描述
商品排名
价格
评论数与评分
站点域名

结果会受到所选地区和语言的影响。地区与语言列表可分别通过以下接口获取：

/v3/merchant/google/locations
/v3/merchant/google/languages

本接口支持两种任务优级：

1：普通优级
2：高优级

高优级通常执行更快，但费用更高。

接口地址

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

计费说明

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

普通任务：以响应中的 cost 字段为准
高优级任务：会产生额外费用
当 depth过 40，且搜索引擎返回 40 条结果时，可能产生额外扣费

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求说明

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

任务创建后，您可以：

使用返回的任务 id 轮询获取结果；
在创建任务时指定 postback_url 或 pingback_url，由系统在任务完成后主动通知您。

回调说明

postback_url：任务完成后，系统将以 POST 方式推送结果，数据采用 gzip 压缩
pingback_url：任务完成后，系统将以 GET 方式发送通知
若您的服务端在 10 秒未响应，连接会因时中止，任务将转 /v3/merchant/google/products/tasks_ready/ 列表
回调失败时，错误码与错误信息取决于您的服务器

请求参数

字段名	类型	说明
`keyword`	string	。填。最长 `700` 个字符。字段中的 `%##` 会被解码，字符 `+` 会被解码为空格。如果中需要保留 `%`，请写为 `%25`。
`url`	string	搜索请求的完整直链。可选。平台会自动拆解的参数，但这种方式处理难度最高，且 URL 中准确地区和语言信息，通常不推荐。示例：`https://www.google.com/search?q=fish&hl=en&gl=US&gws_rd=cr&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc`
`priority`	integer	任务优级。可选。`1` = 普通优级（默认），`2` = 高优级。高优级会额外收费。
`location_name`	string	地区名。当未提供 `location_code` 或 `location_coordinate` 时填。使用该字段时，无需再传 `location_code` 或 `location_coordinate`。示例：`London,England,United Kingdom`
`location_code`	integer	地区编码。当未提供 `location_name` 或 `location_coordinate` 时填。使用该字段时，无需再传 `location_name` 或 `location_coordinate`。示例：`2840`
`location_coordinate`	string	地理坐标。当未提供 `location_name` 或 `location_code` 时填。格式为 `latitude,longitude,radius`。纬度和经度最多 `7` 位小数，`radius` 最小值为 `199.9`。示例：`53.476225,-2.243572,200`
`language_name`	string	语言名。当未提供 `language_code` 时填。使用该字段时，无需再传 `language_code`。示例：`English`
`language_code`	string	语言代码。当未提供 `language_name` 时填。使用该字段时，无需再传 `language_name`。示例：`en`
`se_domain`	string	搜索引擎域名。可选。默认会根据地区和语言自动选择，也可手动指定，如 `google.co.uk`、`google.com.au`、`google.de`。
`depth`	integer	抓取深度，即要获取的 Google Shopping 结果数。可选。默认 `40`，最大 `120`。每 `40` 条结果通常按一个 SERP 计费； `40` 可能产生额外费用。
`max_crawl_pages`	integer	最大抓取页数。可选。最大值 `7`。该参数与 `depth` 组合影响抓取范围。
`search_param`	string	附加搜索参数。可选。用于自定义筛选和排序。示例：`&tbs=ppr_min:45`（价格大于 45）、`&tbs=ppr_max:50`（价格小于 50）、`&tbs=p_ord:p`（价格升序）、`&tbs=p_ord:pd`（价格降序）、`&tbs=p_ord:rv`（按评分排序）、`&tbs=ppr_max:50,p_ord:rv`（价格不高于 50 且按评分排序）、`&udm=28`（使用新版 Shopping 标记，默认返回 40 条 SERP，`depth` 最大可到 `200`，且 `url` 中不能带 `tbm=shop`）、`&shoprs=$value`（新版 Shopping 的高级筛选/排序参数，`$value` 为 protobuf Base64 字符串）。注意：如果指定了 `price_min`、`price_max` 或 `sort_by`，则会忽略 `search_param`。
`price_min`	integer	商品最低价格。可选。示例：`5`。如果指定该字段，将忽略 `search_param`。
`price_max`	integer	商品最高价格。可选。示例：`100`。如果指定该字段，将忽略 `search_param`。
`sort_by`	string	排序方式。可选。支持：`review_score`、`price_low_to_high`、`price_high_to_low`。示例：`review_score`。如果指定该字段，将忽略 `search_param`。
`tag`	string	自定义任务标识。可选。最长 `255` 个字符。便于后续将结果与业务侧记录对应。响应中的 `data` 对象会返回该值。
`postback_url`	string	结果推送地址。可选。任务完成后，系统会将结果以 `gzip` 压缩后的 `POST` 请求发送到该地址。支持在 URL 中使用 `$id` 和 `$tag` 变量。示例：`http://your-server.com/postbackscript?id=$id`、`http://your-server.com/postbackscript?id=$id&tag=$tag`。URL 中特殊字符会自动 URL 编码，例如 `#` 会变为 `%23`。
`postback_data`	string	`postback_url` 的数据类型。指定 `postback_url` 时填。可选值：`advanced`、`html`。
`pingback_url`	string	任务完成通知地址。可选。任务完成后，系统会向该地址发送 `GET` 请求。支持在 URL 中使用 `$id` 和 `$tag` 变量。示例：`http://your-server.com/pingscript?id=$id`、`http://your-server.com/pingscript?id=$id&tag=$tag`。URL 中特殊字符会自动 URL 编码。

返回结果说明

接口返回 JSON 数据，一个 tasks 数组，每个对应一个已创建任务的信息。

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	接口整体状态码
`status_message`	string	接口整体状态信息
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总费用，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务总数
`tasks_error`	integer	`tasks` 数组中出错的任务数
`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	请求路径信息
`data`	object	与创建任务时传参数一致的数据对象
`result`	array \| null	结果数组。对于任务创建接口，此处通常为 `null`

建议对 status_code 和任务级错误状态做完整异常处理，因单任务失败影响批量调用流程。

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/merchant/google/products/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "United States",
 "language_name": "English",
 "keyword": "iphone"
 },
 {
 "location_name": "United States",
 "language_name": "English",
 "keyword": "hedonism wines",
 "price_min": 10,
 "sort_by": "price_low_to_high",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "United States",
 "language_name": "English",
 "keyword": "iphone",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript"
 }
]'

Python

python

import requests

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

data = [
 {
 # 示例1：基础任务
 "location_name": "United States",
 "language_name": "English",
 "keyword": "iphone"
 },
 {
 # 示例2：带价格筛选、排序和高优级
 "location_name": "United States",
 "language_name": "English",
 "keyword": "hedonism wines",
 "price_min": 10,
 "sort_by": "price_low_to_high",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 # 示例3：任务完成后推送结果
 "location_name": "United States",
 "language_name": "English",
 "keyword": "iphone",
 "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: "iphone",
 price_min: 10,
 sort_by: "price_low_to_high",
 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/google/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.error(error);
 });

返回示例

json

{
 "version": "0.1.20200416",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0712 sec.",
 "cost": 0.001,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "merchant",
 "function": "products",
 "se": "google",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "iphone",
 "price_min": "5",
 "se_type": "shopping",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码与错误处理

顶层 status_code = 20000 表示请求成功受理
单个任务也有独立的 status_code，批量请求时应逐条检查
若单次 POST过 100 个任务，出部分会返回 40006
完整错误码定义请参考文档中的 /v3/appendix/errors

建议在业务侧重点处理以下场景：

请求体不是 JSON 数组
缺少 keyword
未提供有效的地区参数或语言参数
postback_url 已设置但缺少 postback_data
批量任务数限制
回调地址时或不可达

使用建议

优使用 keyword + 地区 + 语言 方式建任务 这是最稳定、最易维护的调用方式。
如非，不建议使用 url 直链方式 虽然更灵活，但对 URL 的结构要求更高，也更容易因参数不完整导致解析失败。
筛选逻辑优用结构化字段 如价格和排序，优使用 price_min、price_max、sort_by，可读性和可控性更好。
批量任务控制在每次 100 条 便于管理失败重试与成本控制。
异步场景优考虑回调 如果抓取任务量较大，建议使用 postback_url 或 pingback_url，降低轮询成本。

实用场景

监控商品词搜索结果：按持续抓取 Google Shopping 商品列表，观察品牌或竞品在购物结果中的。
筛选价格区间商品：通过 price_min、price_max 获取指定价格带商品，支持电商价格带分析与选品研究。
跟踪竞品排序变化：结合 sort_by 与地区/语言参数，分析竞品在不同市场中的价格排序或评价排序表现。
构建购物搜索报库：批量创建任务，沉淀商品标题、价格、评分、域名等字段，用于后续 SEO 与市场分析。
触发异步回调处理流程：通过 postback_url 或 pingback_url 在任务完成后自动接收通知，便于对接数据管道或报表系统。

merchant/google/products/task_post ​

设置 Google Shopping 商品抓取任务 ​

接口地址 ​

计费说明 ​

请求说明 ​

回调说明 ​

请求参数 ​

返回结果说明 ​

顶层字段 ​

tasks[] 字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

返回示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​