SeerMarTech API 文档

主题

提交 Google 扩展评论采集任务 ​

该接口用于创建 Google 扩展评论采集任务，返回对象来自搜索结果中的 Reviews 模块。除 Google 用户评论外，还可能来自可信评论来源的数据，例如 TripAdvisor、Yelp、Trustpilot 等。

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

接口说明 ​

  • 请求方法：POST
  • 请求地址：https://api.seermartech.cn/v3/business_data/google/extended_reviews/task_post

计费说明 ​

本接口按两部分计费：

  1. 任务提交费用
  2. 返回评论数量费用

需要特别注意：

  • items 数组中每返回 20 条评论 计费一次；
  • 例如设置 "depth": 21，将按 40 条评论档位 计费；
  • 建议将 depth 设置为 20 的倍数，以获得更稳定的计费预期；
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

若原始标准单价为 USD 计费，则可按如下方式估算人民币价格：

  • 参考价以响应头 X-SeerMarTech-Charge-CNY 为准
  • 例如：若某次基础请求成本为 USD 0.0045，则 参考价约 ¥0.0720 / 次

此外，不同任务参数会影响费用倍率：

  • 使用 keyword：该类任务按 Google Reviews API 标准费率的 3 倍计费
  • 使用 cid：按标准费率的 2 倍计费
  • 使用 place_id：按标准费率的 2 倍计费
  • 使用 priority=2：高优级执行，需额外加价

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

请求体格式 ​

所有 POST 数据使用 UTF-8 编码的 JSON，并以 JSON 数组 形式提交：

json
[
 {
 "location_name": "London,England,United Kingdom",
 "language_name": "English",
 "keyword": "hedonism wines"
 }
]

请求限制 ​

  • 每分钟最多可发起 2000 次 API 调用
  • 每个 POST 请求最多 100 个任务 -出 100 个任务的部分将返回错误：40006

回调机制 ​

任务创建后，可通过返回的唯一任务 ID 获取结果。 如果在创建任务时设置了 postback_url 或 pingback_url，本平台也可在任务完成后主动通知或推送结果。

回调行为说明 ​

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

变量替换 ​

在回调地址中可以使用以下占位符：

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

示例：

  • 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 列表，供后续主动拉取。

请求参数 ​

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

字段名类型说明
keywordstring。若未提供 cid 或 place_id，则此字段填。应填写本地商家/地点名称。最大长度 700 字符。 %## 会被解码，+ 会被解码为空格。如需传递字面量 %，请写为 %25。若该字段 allinanchor:、allintext:、allintitle:、allinurl:、define:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、related:、site: 等高级搜索操作符，则单任务费用乘以 5。 cache: 的查询不受支持，会返回校验错误。注意： 使用该字段时，任务按 Google Reviews API 标准费率的 3 倍计费。
cidstring商家实体的 Google 唯一 ID。若未提供 keyword 或 place_id，则此字段填。示例：194604053573767737。注意： 使用该字段时，任务按标准费率的 2 倍计费。
place_idstringGoogle 地图中的商家实体标识。若未提供 keyword 或 cid，则此字段填。示例：GhIJQWDl0CIeQUARxks3icF8U8A。注意： 使用该字段时，任务按标准费率的 2 倍计费。
priorityinteger任务优级，可选。支持：1 = 普通优级（默认），2 = 高优级。使用高优级会产生额外费用。
location_namestring搜索地区名。若未提供 location_code 或 location_coordinate，则此字段填。使用该字段时无需再传 location_code 或 location_coordinate。可通过 /v3/business_data/google/locations 获取支持的地区列表。示例：London,England,United Kingdom
location_codeinteger搜索地区编码。若未提供 location_name 或 location_coordinate，则此字段填。使用该字段时无需再传 location_name 或 location_coordinate。可通过 /v3/business_data/google/locations 获取支持的地区编码。示例：2840
location_coordinatestring指定位置的 GPS 坐标。若未提供 location_name 或 location_code，则此字段填。格式：latitude,longitude,radius。纬度和经度最多 7 位小数，radius 最小值为 199.9。示例：53.476225,-2.243572,200
language_namestring搜索语言名。若未提供 language_code，则此字段填。使用该字段时无需再传 language_code。可通过 /v3/business_data/google/languages 获取支持语言列表。示例：English
language_codestring搜索语言代码。若未提供 language_name，则此字段填。使用该字段时无需再传 language_name。可通过 /v3/business_data/google/languages 获取支持语言代码。示例：en
depthinteger采集深度，可选，表示要抓取的评论数量。默认值：20；最大值：1000。建议使用 20 的倍数。系统按每最多 20 条结果一个计费档位计费；当 depth > 20 且搜索引擎返回 20 条结果时，会产生额外费用。
tagstring自定义任务标识，可选。最大长度 255 字符。可用于将任务与业务侧记录，返回结果中会原样出现在 data 对象。
postback_urlstring结果推送地址，可选。任务完成后，本平台会将 gzip 压缩后的结果通过 POST 请求发送到该地址。支持 $id 和 $tag 占位符。特殊字符会进行 URL 编码，例如 # 会被编码为 %23。
pingback_urlstring完成通知地址，可选。任务完成后，本平台会向该地址发起 GET 请求。支持 $id 和 $tag 占位符。特殊字符会进行 URL 编码，例如 # 会被编码为 %23。

响应结构 ​

接口返回 JSON 数据 tasks 数组，记录本次提交的任务信息。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
status_codeinteger通用状态码。完整错误码请参考 /v3/appendix/errors
status_messagestring通用状态信息
timestring执行耗时，单位秒
costfloat本次请求总费用，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorintegertasks 数组中返回错误的任务数量
tasksarray任务列表

tasks 数组字段 ​

字段名类型说明
idstring平台唯一任务 ID，UUID 格式
status_codeinteger任务状态码，范围通常为 10000-60000
status_messagestring任务状态信息
timestring任务执行耗时，单位秒
costfloat单个任务费用，单位 USD
result_countintegerresult 数组中的数量
patharrayURL 路径
dataobject与提交时传参数一致的数据对象
resultarray / null结果数组。创建任务时此处通常为 null

结果获取说明 ​

该接口用于创建任务。成功创建后，result 一般为 null。 任务完成后，您可以：

  • 使用任务 id 调用对应结果接口拉取数据；
  • 或通过 postback_url / pingback_url 接收异步通知。

示例请求 ​

cURL ​

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

Python ​

python
import requests

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

# 按平台要求，POST 请求体使用 JSON 数组
payload = [
 {
 "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": 40,
 "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=payload)
print(response.status_code)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

const postArray = [
 {
 location_name: "London,England,United Kingdom",
 language_name: "English",
 keyword: "hedonism wines",
 depth: 40,
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/business_data/google/extended_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.response?.data || error.message);
 });

示例响应 ​

json
{
 "version": "0.1.20241028",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0681 sec.",
 "cost": 0.0045,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0023 sec.",
 "cost": 0.0045,
 "result_count": 0,
 "path": [
 "v3",
 "business_data",
 "google",
 "extended_reviews",
 "task_post"
 ],
 "data": {
 "api": "business_data",
 "function": "extended_reviews",
 "location_name": "London,England,United Kingdom",
 "language_name": "english",
 "cid": "17626775537598922320",
 "se_type": "extended_reviews",
 "se": "google",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

常见状态与错误处理 ​

代码含义
20000请求成功
20100任务已创建
40006单次 POST 中任务数 100
校验错误参数格式或参数组合不合法，例如缺少位置/语言/目标标识，或 keyword 中不受支持的 cache: 操作符

建议在集成时重点处理以下：

  • 顶层 status_code 非 20000
  • tasks_error 大于 0
  • 某个任务的 status_code 非成功状态
  • 回调地址时或不可达
  • 由于 depth 设置较大导致费用出预期

使用建议 ​

  1. 优使用稳定标识符
  • 若已掌握商家的 cid 或 place_id，通常比模糊更稳定。
  1. 合理控制 depth
  • 建议从 20 或 40 开始，一次请求抓取过深导致费用上升。
  1. 使用 tag 做业务映射
  • 可将门店 ID、项目 ID、批次号写 tag，便于结果回流和任务追踪。
  1. 启用异步回调
  • 大规模任务建议合 postback_url 或 pingback_url 使用，减少轮询成本。

实用场景 ​

  • 监控门店口碑来源分布：抓取某商家在 Google 评论模块中的扩展评论来源，识别评论是否来自 Yelp、TripAdvisor、Trustpilot 等平台，帮助品牌统一管理口碑渠道。
  • 追踪区域化评论表现：按不同 location_name 或 location_coordinate 提交同一商家任务，比较不同地区下评论展示差异，为本地化 SEO 和门店运营提供依据。
  • 批量巡检连锁门店评价：通过 cid、place_id 或门店名批量建任务，快速发现哪些门店在搜索结果中有较强评论可见性，连锁品牌门店优化。
  • 验证品牌词下的评论：针对品牌名或门店名提交 keyword 查询，观察搜索结果中的评论模块是否展示，评估品牌词 SERP 占位质量。
  • 构建异步评论采集流水线：结合 postback_url 或 pingback_url，将任务提交、完成通知、结果库串联起来，适用于大规模本地商家评论监测系统。

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

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