创建 Google Reviews 抓取任务

POST /v3/business_data/google/reviews/task_post

本接口用于创建 Google 搜索结果中 Reviews（评论）模块 的抓取任务。返回结果与所选的地理位置和语言强，因此创建任务时需要提供位置与语言参数。

接口路径：

POST https://api.seermartech.cn/v3/business_data/google/reviews/task_post

功能说明

通过本接口创建任务后，平台会异步抓取指定商家在 Google 评论模块中的评论数据。你可以通过任务返回的唯一 id 获取结果，也可以在创建任务时提供 postback_url 或 pingback_url，由平台在任务完成后主动通知或回传结果。

计费说明

• 创建任务会产生费用；
• 同时会按 items 中返回的评论数量计费；
• 每返回 10 条评论计费一次；
• 例如：设置 "depth": 11，将按 20 条评论 计费；
• 如设置高优级 priority = 2，会产生额外费用；
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

如按平台常见单价 USD 0.002 / 10 条评论 估算，参考价约 ¥0.0320 / 次。若更多评论或高优级任务，费用会相应增加。

请求说明

• 请求方式：POST
• 请求体格式：application/json
• 编码：UTF-8
• 请求体为 JSON 数组：[{ ... }]

频率与批量限制

• 每分钟最多可发送 2000 次 API 调用
• 每次 POST 最多 100 个任务 -过 100 个任务时，出部分会返回错误码 40006

异步结果获取方式

创建任务后可通过以下方式获取结果：

1. 按任务 ID 查询

• 使用响应中返回的唯一任务 id 获取后续结果

2. 任务完成后主动通知

• pingback_url：任务完成后发送 GET 通知
• postback_url：任务完成后以 POST 方式回传压缩后的结果（gzip）

回调时说明

如果你的服务端在 10 秒 未响应，连接会因时被中止，任务会被转 /v3/business_data/google/reviews/tasks_ready 列表中。错误码和错误消息取决于你的服务端。

---

请求参数

以下为创建任务时可用字段说明。

字段名	类型	说明
keyword	string	商家名称。当未提供 cid 或 place_id 时填。最长 700 个字符。 %## 会被解码，+ 会被解码为空格。如需传 % 字符，请写为 %25。若该字段 allinanchor:、allintext:、allintitle:、allinurl:、define:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、related:、site: 等搜索操作符，单任务费用将乘以 5。 cache: 的查询不受支持，会返回参数校验错误。
cid	string	商家的 Google 唯一标识。当未提供 keyword 或 place_id 时填。示例：194604053573767737
place_id	string	Google Maps 中的商家标识。当未提供 keyword 或 cid 时填。示例：GhIJQWDl0CIeQUARxks3icF8U8A
priority	integer	任务优级，可选。1 = 普通优级（默认）；2 = 高优级。高优级会额外收费。
location_name	string	搜索位置名。当未提供 location_code 或 location_coordinate 时填。使用该字段时，无需再传 location_code 或 location_coordinate。位置列表可通过 /v3/business_data/google/locations 获取。示例：London,England,United Kingdom
location_code	integer	搜索位置编码。当未提供 location_name 或 location_coordinate 时填。使用该字段时，无需再传 location_name 或 location_coordinate。位置列表可通过 /v3/business_data/google/locations 获取。示例：2840
location_coordinate	string	GPS 坐标定位。当未提供 location_name 或 location_code 时填。格式为：latitude,longitude,radius。latitude 和 longitude 最多 7 位小数；radius 最小值为 199.9。示例：53.476225,-2.243572,200
language_name	string	搜索语言名。当未提供 language_code 时填。使用该字段时，无需再传 language_code。语言列表可通过 /v3/business_data/google/languages 获取。示例：English
language_code	string	搜索语言代码。当未提供 language_name 时填。使用该字段时，无需再传 language_name。语言列表可通过 /v3/business_data/google/languages 获取。示例：en
depth	integer	抓取深度，可选。表示需要抓取的评论数量。默认值：10；最大值：4490。建议按 10 的倍数设置，因为系统按每 10 条评论一组处理。 10 可能带来额外费用。
sort_by	string	评论排序方式，可选。可选值：newest（最新）、highest_rating（评分最高）、lowest_rating（评分最低）、relevant（性，默认）
tag	string	自定义任务标识，可选。最大长度 255。可用于业务侧任务与结果；设置后会出现在响应的 data 对象中。
postback_url	string	结果回传地址，可选。任务完成后，平台会将结果以 gzip 压缩的 POST 请求发送到该地址。可使用 $id 作为任务 ID 变量，$tag 作为 URL 编码后的标签变量。示例：http://your-server.com/postbackscript?id=$id、http://your-server.com/postbackscript?id=$id&tag=$tag。注意：特殊字符会被 URL 编码，例如 # 会被编码为 %23。
pingback_url	string	完成通知地址，可选。任务完成后，平台会向该地址发送 GET 请求。可使用 $id 作为任务 ID 变量，$tag 作为 URL 编码后的标签变量。示例：http://your-server.com/pingscript?id=$id、http://your-server.com/pingscript?id=$id&tag=$tag。注意：特殊字符会被 URL 编码，例如 # 会被编码为 %23。

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/business_data/google/reviews/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "London,England,United Kingdom",
 "language_name": "English",
 "keyword": "hedonism wines",
 "depth": 50,
 "sort_by": "highest_rating",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]'

Python

import requests

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

# 请求体为 JSON 数组
payload = [
 {
 "location_name": "London,England,United Kingdom",
 "language_name": "English",
 "keyword": "hedonism wines",
 "depth": 50,
 "sort_by": "highest_rating",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "location_name": "London,England,United Kingdom",
 "language_name": "English",
 "keyword": "hedonism wines",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

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

TypeScript

import axios from "axios";

// 请求体为 JSON 数组
const postArray = [
 {
 location_name: "London,England,United Kingdom",
 language_name: "English",
 keyword: "hedonism wines",
 depth: 50,
 sort_by: "highest_rating",
 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/business_data/google/reviews/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 数据 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 数组中返回错误的任务数量
tasks	array	任务列表

tasks 数组字段

字段名	类型	说明
id	string	平台唯一任务 ID，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务状态消息
time	string	任务执行耗时，单位秒
cost	float	该任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	URL 路径
data	object	你在 POST 请求中提交的参数回显
result	array	结果数组。创建任务接口中该值为 null

建议在生产环境中对 status_code、tasks_error 以及任务级错误进行完整处理。

---

响应示例

{
 "version": "0.1.20200325",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1329 sec.",
 "cost": 0.00375,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0312 sec.",
 "cost": 0.00375,
 "result_count": 0,
 "path": [
 "v3",
 "business_data",
 "google",
 "reviews",
 "task_post"
 ],
 "data": {
 "api": "reviews",
 "function": "task_post",
 "se": "google",
 "location_name": "London,England,United Kingdom",
 "language_name": "English",
 "keyword": "hedonism wines",
 "depth": 50,
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

---

使用建议

1. 优使用明确的商家标识

如果你已经掌握商家的 cid 或 place_id，建议优使用，而不是依赖 keyword，这样通常能获得更稳定的匹结果。

2. depth 尽量按 10 的倍数设置

由于评论按每 10 条一组处理，设置为 10、20、30、50 等值更利于控制成本和结果预期。

3. 大批量任务请分批提交

单次 POST 最多 100 个任务，建议业务侧自行做批次拆分与失败重试。

4. 回调服务要保证及时响应

无论使用 pingback_url 还是 postback_url，都应确保接收服务在 10 秒完成响应，任务回落到拉取列表。

---

常见错误与注意事项

• 缺少商家定位参数

• keyword、cid、place_id 三至少提供一个

• 缺少位置参数

• location_name、location_code、location_coordinate 三至少提供一个

• 缺少语言参数

• language_name 与 language_code 至少提供一个

• 单次创建任务数 100 -出部分返回 40006

• keyword含不支持的搜索参数 -含 cache: 会触发校验错误

• 回调地址特殊字符未考虑编码

• 平台会自动进行 URL 编码，业务侧需注意解析

---

实用场景

• 监控门店口碑变化：定期抓取指定商家的最新评论，及时发现评分下滑、服务投诉或高频负面主题。
• 对比竞品评价结构：抓取竞品在不同地区的评论与评分排序结果，本地商家优化服务策略。
• 筛选高分或低分评论：通过 sort_by 按最高分或最低分排序，快速定位型好评/差评，支持运营复盘。
• 构建本地商家评论数据库：批量提交多门店任务，沉淀评论、评分趋势与地域差异数据，用于 BI 分析。
• 触发自动化舆预警：结合 pingback_url 或 postback_url，在任务完成后自动感分析、投诉识别或工单系统。