Google Reviews 任务创建

POST /v3/reviews/google/task_post

接口概述

此接口用于创建 Google Reviews 抓取任务，返回 Google 搜索结果页中“Reviews”模块的评论数据。

返回结果与所选的地理位置和语言强，因此创建任务时正确指定 location 与 language 参数。

注意：

• keyword 应填写本地商家名称，否则可能无法获取有效评论。
• 也可以直接传商家标识参数，例如 cid 或 place_id。
• 系统按 items 数组中返回的评论数量计费，每 10 条评论为一个计费单位。例如设置 "depth": 11，将按 20 条评论对应的档位计费。
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求地址

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

计费说明

该接口的费用由两部分组成：

1. 创建任务的基础费用
2. 返回评论数量对应的费用

由于评论按每 10 条为一组处理，建议将 depth 设置为 10 的倍数，以获得更稳定的成本与结果预期。

如参考单价发生变化，请以接口响应中的 cost 字段为准。

请求方式与频率限制

• 请求方式：POST
• 请求体格式：JSON
• 编码：UTF-8
• 请求体为 JSON 数组：[{...}]
• 单次 POST 最多可提交 100 个任务
• 每分钟最多可发起 2000 次 API 调用

结果获取方式

任务提交后，可通过以下方式获取结果：

1. 使用任务唯一标识 id 轮询获取结果
2. 创建任务时传 postback_url，任务完成后平台将把结果以 gzip 压缩的 POST 请求推送到指定地址
3. 创建任务时传 pingback_url，任务完成后平台将向指定地址发送 GET 通知

回调说明

• postback_url：推送完整结果
• pingback_url：通知任务完成，通常用于触发后续拉取
• URL 中支持占位符：
• $id：任务 id
• $tag：经过 URL 编码的任务 tag

示例：

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

时说明： 如果回调目标服务器在 10 秒未响应，连接会因时中止，任务结果会“Tasks Ready”列表，需改为主动拉取。

---

请求参数

任务参数字段说明

字段名	类型	说明
keyword	string	填。查询，应指向本地商家名称。最长 700 个字符。所有 %## 会被解码，+ 会被解码为空格。如果需要使用 %，请写为 %25。如 allinanchor:、allintext:、allintitle:、allinurl:、define:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、related:、site: 等高级搜索参数，单任务费用将乘以 5。 cache: 的查询不受支持，会返回校验错误。该字段也可用于传 cid 或 place_id。示例：cid:194604053573767737、place_id:GhIJQWDl0CIeQUARxks3icF8U8A
priority	integer	可选。任务优级。1 = 普通优级（默认）；2 = 高优级。高优级任务会额外收费，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
location_name	string	当未传 location_code 或 location_coordinate 时填。搜索位置完整名称。使用该字段时，无需再传 location_code 或 location_coordinate。可通过 /v3/reviews/google/locations 获取可用地点列表。示例：London,England,United Kingdom
location_code	integer	当未传 location_name 或 location_coordinate 时填。搜索位置编码。使用该字段时，无需再传 location_name 或 location_coordinate。可通过 /v3/reviews/google/locations 获取。示例：2840
location_coordinate	string	当未传 location_name 或 location_code 时填。位置 GPS 坐标，格式为 latitude,longitude,radius。latitude 与 longitude 最多支持 7 位小数；radius 最小值为 199.9。使用该字段时，无需再传 location_name 或 location_code。示例：53.476225,-2.243572,200
language_name	string	当未传 language_code 时填。搜索语言完整名称。使用该字段时，无需再传 language_code。可通过 /v3/reviews/google/languages 获取。示例：English
language_code	string	当未传 language_name 时填。搜索语言编码。使用该字段时，无需再传 language_name。可通过 /v3/reviews/google/languages 获取。示例：en
depth	integer	可选。抓取评论数量，即 SERP 中评论解析深度。默认值：10。强烈建议设置为 10 的倍数。
sort_by	string	可选。评论排序方式。可选值：newest（最新优）、highest_rating（高评分优）、lowest_rating（低评分优）、relevant（性优，默认）。
tag	string	可选。自定义任务标识，最长 255 字符。用于任务与业务数据，返回结果中的 data 数组会带回该值。
postback_url	string	可选。任务完成后，平台会将结果以 gzip 压缩的 POST 请求发送到该地址。支持 $id、$tag 占位符。
pingback_url	string	可选。任务完成后，平台会向该地址发送 GET 通知。支持 $id、$tag 占位符。

---

请求示例

cURL

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

Python

import requests

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

data = [
 {
 "location_name": "London,England,United Kingdom",
 "language_name": "English",
 "keyword": "hedonism wines"
 },
 {
 "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, headers=headers, json=data)
print(response.json)

TypeScript

import axios from "axios";

const postData = [
 {
 location_name: "London,England,United Kingdom",
 language_name: "English",
 keyword: "hedonism wines"
 },
 {
 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"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/reviews/google/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postData
})
 .then((response) => {
 // 输出任务创建结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

---

响应说明

接口返回 JSON 数据，任务创建状态与任务信息。

顶层响应字段

字段名	类型	说明
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	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	array	创建任务时传的参数回显
result	array / null	结果数组；创建任务时此字段通常为 null

---

响应示例

{
 "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.0042 sec.",
 "cost": 0.00375,
 "result_count": 0,
 "path": [
 "v3",
 "reviews",
 "google",
 "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. 顶层状态

• status_code
• status_message

2. 任务级状态

• tasks[].status_code
• tasks[].status_message

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

建议：

• 判断顶层 status_code 是否成功
• 再逐个检查 tasks 中每个任务的状态
• 对回调时、参数校验失败、任务创建失败等设计重试或补偿机制

使用建议

• 优使用明确的商家名称，过于泛化的
• 需要稳定控制成本时，depth 尽量设置为 10、20、30 等 10 的倍数
• 若已知商家唯一标识，优使用 cid: 或 place_id:，可提高命中准确性
• 对批量任务，建议使用 tag 建立业务侧映射
• 异步场景优合 postback_url 或 pingback_url 使用

实用场景

• 监控门店口碑变化：定期抓取指定门店评论，跟踪评分与新增评论趋势，帮助本地商家及时发现服务问题。
• 对比竞品评论表现：抓取同区域竞品门店评论，分析高分与低分反馈差异，为优化服务和策略提供依据。
• 筛选高价值差评：按 lowest_rating 排序抓取评论，快速定位负面反馈，提升客服响应效率与品牌修复速度。
• 挖掘最新用户反馈：按 newest 排序获取最新评论，用于门店运营、产品改进和活动复盘。
• 基于商家唯一标识精准采集：使用 cid 或 place_id 直接获取指定实体的评论，减少歧义带来的抓取偏差。