创建 Google Shopping 商品评价采集任务

接口说明

该接口用于为指定商品创建 Google Shopping 评价采集任务，返回目标商品的评论列表。

返回结果与请求中指定的 gid 强。建议在请求时同时提供 gid、data_docid 和 product_id，以获得更稳定、准确的结果。

接口路径：

POST /v3/merchant/google/reviews/task_post

完整请求地址：

https://api.seermartech.cn/v3/merchant/google/reviews/task_post

计费说明

本接口在创建任务时扣费。

此外，评价结果按每 10 条评论 为一个计费单。例如：

若设置 "depth": 10，按 10 条计费
若设置 "depth": 11，即使只多 1 条，也会按 20 条计费

因此，建议将 depth 设置为 10 的倍数。

如原始单价涉及，换算请以接口返回的 cost 字段为准。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求方式

方法：POST
Content-Type：application/json
请求体格式：JSON 数组 [{ ... }]
单次 POST 最多提交 100 个任务
频率限制：最多 2000 次 API 调用/分钟
若单次请求 100 个任务，出部分会返回错误 40006

任务结果获取方式

任务创建成功后，可通过返回的任务唯一标识 id 获取结果。

你也可以在创建任务时设置以下回调参数：

postback_url：任务完成后，本平台会将结果以 gzip 压缩的 POST 请求发送到该地址
pingback_url：任务完成后，本平台会向该地址发送 GET 通知

注意：

若你的服务器在 10 秒未响应，连接会因时中断 -时后，任务会被转 /v3/merchant/google/reviews/tasks_ready/ 列表，供后续拉取
回调地址中的特殊字符会进行 URL 编码，例如 # 会被编码为 %23

请求参数

字段名	类型	填	说明
`gid`	string	是	Google Shopping 商品的局商品标识。建议与 `data_docid`、`product_id` 一起传。示例：`4702526954592161872`
`product_id`	string	否	Google Shopping 商品唯一标识。建议与 `gid`、`data_docid` 一起传。示例：`4485466949985702538`
`data_docid`	string	否	SERP 数据唯一标识。建议与 `gid`、`product_id` 一起传。示例：`13071766526042404278`
`priority`	integer	否	任务优级。`1` = 普通优级（默认）；`2` = 高优级。高优级会产生额外费用。
`location_name`	string	条件填	搜索引擎地区名。若未传 `location_code` 或 `location_coordinate`，则填。使用该字段时无需再传 `location_code`、`location_coordinate`。示例：`HA1,England,United Kingdom`
`location_code`	integer	条件填	搜索引擎地区编码。若未传 `location_name` 或 `location_coordinate`，则填。使用该字段时无需再传 `location_name`、`location_coordinate`。示例：`9045969`
`location_coordinate`	string	条件填	GPS 坐标，格式为 `latitude,longitude,radius`。若未传 `location_name` 或 `location_code`，则填。`latitude` 和 `longitude` 最多 7 位小数；`radius` 最小值为 `199.9`。示例：`53.476225,-2.243572,200`
`language_name`	string	条件填	搜索语言名。若未传 `language_code`，则填。使用该字段时无需再传 `language_code`。示例：`English (United Kingdom)`
`language_code`	string	条件填	搜索语言编码。若未传 `language_name`，则填。使用该字段时无需再传 `language_name`。示例：`en_GB`
`se_domain`	string	否	搜索引擎域名。默认会根据地区和语言自动选择，也可手动指定。示例：`google.co.uk`、`google.com.au`、`google.de`
`depth`	integer	否	采集深度，即要抓取的评论数量。默认 `10`，最大 `8000`。建议设置为 10 的倍数。 10 后，如返回结果一个 10 条计费单，会产生额外费用。
`tag`	string	否	自定义任务标识，最大长度 `255` 字符。便于业务侧对账、追踪与结果匹。
`postback_url`	string	否	任务完成后接收结果的回调地址。本平台会向该地址发送 gzip 压缩的 POST 请求。支持使用 `$id` 和 `$tag` 变量。示例：`http://your-server.com/postbackscript?id=$id&tag=$tag`
`postback_data`	string	否	`postback_url` 返回的数据类型。可选值：`advanced`
`pingback_url`	string	否	任务完成通知地址。本平台会向该地址发起 GET 请求。支持使用 `$id` 和 `$tag` 变量。示例：`http://your-server.com/pingscript?id=$id&tag=$tag`

地区与语言接口

如需获取可用地区和语言，可调用以下容路径：

地区列表：/v3/merchant/google/locations
语言列表：/v3/merchant/google/languages

如需获取商品的 gid、product_id、data_docid，可调用：

商品接口：/v3/merchant/google/products/task_post

返回结果说明

接口返回 JSON 数据，顶层 tasks 数组，用于描述本次创建的任务。

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码，完整错误码可参考 `/v3/appendix/errors`
`status_message`	string	通用状态说明
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总费用
`tasks_count`	integer	`tasks` 数组中的任务数
`tasks_error`	integer	`tasks` 数组中出错的任务数
`tasks`	array	任务列表

`tasks[]` 字段

字段名	类型	说明
`id`	string	本平台中的唯一任务 ID，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态说明
`time`	string	任务处理耗时
`cost`	float	该任务费用
`result_count`	integer	`result` 数组数量
`path`	array	请求路径
`data`	object	与提交时相同的请求参数
`result`	array \| null	创建任务接口中该值通常为 `null`

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/merchant/google/reviews/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)",
 "gid": "4702526954592161872"
 }
]'

Python

python

import requests

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

# 请求体为 JSON 数组
payload = [
 {
 "location_name": "United States",
 "language_name": "English (United States)",
 "gid": "4702526954592161872"
 },
 {
 "location_name": "United States",
 "language_name": "English (United States)",
 "gid": "4702526954592161872",
 "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)",
 "gid": "4702526954592161872",
 "postback_data": "advanced",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

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

TypeScript

typescript

import axios from "axios";

const payload = [
 {
 // 基础任务：指定地区、语言和 gid
 location_name: "United States",
 language_name: "English (United States)",
 gid: "4702526954592161872"
 },
 {
 // 高优级任务：完成更快，但费用更高
 location_name: "United States",
 language_name: "English (United States)",
 gid: "4702526954592161872",
 priority: 2,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 // 通过 postback 接收完整结果
 location_name: "United States",
 language_name: "English (United States)",
 gid: "4702526954592161872",
 postback_data: "advanced",
 postback_url: "https://your-server.com/postbackscript"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/merchant/google/reviews/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

{
 "version": "0.1.20231117",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0676 sec.",
 "cost": 0.00075,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "1c8b0f2e-6f2e-4d4d-9d79-1e0d6b6f1234",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0031 sec.",
 "cost": 0.00075,
 "result_count": 0,
 "path": [
 "v3",
 "merchant",
 "google",
 "reviews",
 "task_post"
 ],
 "data": {
 "api": "merchant",
 "function": "reviews",
 "se": "google",
 "language_code": "en",
 "location_code": 2840,
 "gid": "4702526954592161872",
 "se_type": "reviews",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码与错误处理

建议在接时同时处理两层状态：

顶层状态：status_code、status_message
任务级状态：tasks[].status_code、tasks[].status_message

常见注意事项：

20000：请求成功 -过单次 100 个任务限制时，出部分返回 40006
任务创建接口返回时，result 通常为 null，需后续通过任务 ID 获取结果或回调
错误码完整列表可参考容路径：/v3/appendix/errors

使用建议

优同时传 gid、product_id、data_docid，提升匹稳定性
depth 建议使用 10、20、30 这类 10 的倍数，便于控制计费
若有异步处理能力，建议 postback_url 或 pingback_url
若你的业务依赖快速返回，可考虑 priority=2，但需注意额外费用

实用场景

采集商品口碑：抓取指定商品的用户评论，用于评估商品口碑走势与用户满意度。
监控竞品评价：持续跟踪竞品商品的评价变化，识别差评集中点，为选品和优化提供依据。
分析地区差异：结合不同 location_name 或 location_code 抓取评价，比较不同市场的用户反馈差异。
构建评论数据仓库：批量创建任务并通过回调接收结果，沉淀商品评论数据用于 BI 看板与长期趋势分析。
支持选品与广告投放：将评论质量、评论数量与商品表现，判断哪些商品更值得 SEO 或广告预算。

创建 Google Shopping 商品评价采集任务 ​

接口说明 ​

计费说明 ​

请求方式 ​

任务结果获取方式 ​

请求参数 ​

地区与语言接口 ​

返回结果说明 ​

顶层字段 ​

tasks[] 字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​