SeerMarTech API 文档

主题

获取 Google 评论任务结果 ​

通过任务 ID 获取 Google 评论采集结果。

返回结果与创建任务时指定的本地商户名称、搜索引擎、位置和语言参数一一对应。本平台会尽可能高精度地模拟所设置的位置与搜索环境，以便返回结果尽量贴近任务创建时该条件下的搜索结果。

你可以使用响应中的 check_url 在浏览器无痕模式下打开，核验结果是否与搜索页一致。需要注意的是，用户偏好、搜索历史以及个性化因素不会被纳入模拟，因此这些因素不会反映在返回结果中。

接口地址 ​

GET https://api.seermartech.cn/v3/reviews/google/task_get/{id}

计费说明 ​

该接口本身不重复计费，费用只在创建任务时扣除。任务创建后，30 天可多次获取结果。

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

路径参数 ​

参数名类型说明
idstring任务唯一标识，UUID 格式。可在任务创建后的 30 天随时用于获取结果。

返回结构 ​

接口返回 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。完整列表见 /v3/appendix/errors。
status_messagestring任务状态说明。
timestring任务执行耗时，单位秒。
costfloat该任务成本，单位 USD。
result_countintegerresult 数组数量。
patharray请求路径。
dataarray与创建任务时传参数一致的数据。
resultarray结果数据。

result[] 字段 ​

字段类型说明
keywordstring创建任务时传的。返回时会对 %## 进行解码，+ 会被解码为空格。
typestring创建任务时传的搜索引擎类型。
se_domainstring创建任务时传的搜索引擎域名。
location_codeinteger创建任务时传的位置代码。
language_codestring创建任务时传的语言代码。
check_urlstring直达搜索结果页的链接，可用于校验返回结果准确性。
datetimestring获取结果的时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。示例：2019-11-15 12:57:46 +00:00
titlestring搜索结果页中 reviews 模块标题，通常为本地商户名称。
sub_titlestringreviews 模块副标题，通常为地址等附加信息。
ratingarray对应本地商户的评分信息。
feature_idstring搜索结果页中 reviews 模块的唯一标识。
place_idstring搜索结果页中 reviews 模块的 XPath。
cidstring搜索引擎定义的商户唯一客户端 ID。可与 /v3/reviews/google/overview/ 接口合，进一步获取完整评论列表。
reviews_countinteger评论总数。
items_countinteger当前结果中返回的评论条数。创建任务时增大 depth 参数可获取更多评论。
itemsarray评论明细列表。创建任务时增大 depth 参数可获取更多评论。

result[].rating 字段 ​

字段类型说明
rating_typestring评分类型。可能值：Max5、Percents、CustomMax。
valuefloat基于评论计算的平均分。
votes_countinteger投票或评分数量。
rating_maxinteger当前 rating_type 对应的最大分值。

result[].items[] 字段 ​

字段类型说明
typestring评论类型。该接口中通常为 "google_reviews_search"。
rank_groupinteger在同类型组的位置。不同 type 的不计该排序。
rank_absoluteinteger在评论中的绝对排名。
positionstring评论在搜索结果页中的位置，可能值：right。
xpathstring该评论节点的 XPath。
review_textstring评论正文。
time_agostring评论发布时间的相对时间描述。
timestampstring评论发布时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。示例：2019-11-15 12:57:46 +00:00
ratingarray评论提交的评分信息。
reviews_countinteger该评论累计提交的评论数。
photos_countinteger该评论累计提交的图片数。
local_guideboolean是否为本地向导用户。
profile_namestring评论昵称。
profile_urlstring评论主页链接。
profile_image_urlstring评论头像链接。
owner_answerstring商户所有对评论的回复。
owner_time_agostring商户回复的相对发布时间。

result[].items[].rating 字段 ​

字段类型说明
rating_typestring评分类型，可能值：Max5。
valuefloat评分值。
votes_countinteger该评论获得的反馈数。
rating_maxinteger当前评分体系下的最大值；Max5 的最大值为 5。

请求示例 ​

curl ​

bash
id="04011058-0696-0199-0000-2196151a15cb"

curl --location --request GET "https://api.seermartech.cn/v3/reviews/google/task_get/${id}" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python ​

python
import requests

task_id = "02231934-2604-0066-2000-570459f04879"

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

response = requests.get(url, headers=headers)
data = response.json

print(data)

TypeScript ​

typescript
import axios from "axios";

const taskId = "02231934-2604-0066-2000-570459f04879";

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/reviews/google/task_get/${taskId}`,
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then((response) => {
 // 返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

结合 tasks_ready 拉取已完成任务 ​

如果你是异步采集流程，通常会查询已完成任务列表，再逐个调用本接口获取结果。

Python 示例 ​

python
import requests

base_url = "https://api.seermartech.cn"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

# 1. 获取已完成任务列表
ready_resp = requests.get(
 f"{base_url}/v3/reviews/google/tasks_ready",
 headers=headers
)
ready_data = ready_resp.json

results = []

if ready_data.get("status_code") == 20000:
 for task_group in ready_data.get("tasks", []):
 for task_item in task_group.get("result", []) or []:
 endpoint = task_item.get("endpoint")
 task_id = task_item.get("id")

 # 2. 方式一：直接请求返回的 endpoint
 if endpoint:
 resp = requests.get(f"{base_url}{endpoint}", headers=headers)
 results.append(resp.json)

 # 3. 方式二：通过任务 ID 拼接 task_get 路径
 # if task_id:
 # resp = requests.get(
 # f"{base_url}/v3/reviews/google/task_get/{task_id}",
 # headers=headers
 # )
 # results.append(resp.json)

print(results)

TypeScript 示例 ​

typescript
import axios from "axios";

const client = axios.create({
 baseURL: "https://api.seermartech.cn",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
});

async function fetchCompletedReviewTasks {
 const tasksResponses: any[] = [];

 const readyResponse = await client.get("/v3/reviews/google/tasks_ready");
 const readyData = readyResponse.data;

 if (readyData.status_code !== 20000) {
 console.error(
 `error. Code: ${readyData.status_code} Message: ${readyData.status_message}`
 );
 return;
 }

 for (const taskGroup of readyData.tasks || []) {
 for (const task of taskGroup.result || []) {
 if (task.endpoint) {
 // 方式一：直接访问已返回的 endpoint
 const taskGetResponse = await client.get(task.endpoint);
 tasksResponses.push(taskGetResponse.data);
 }

 // 方式二：通过任务 ID 查询
 // if (task.id) {
 // const taskGetResponse = await client.get(
 // `/v3/reviews/google/task_get/${task.id}`
 // );
 // tasksResponses.push(taskGetResponse.data);
 // }
 }
 }

 console.log(tasksResponses);
}

fetchCompletedReviewTasks.catch(console.error);

响应示例 ​

json
{
 "version": "3",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1234 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "04011058-0696-0199-0000-2196151a15cb",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0345 sec.",
 "cost": 0,
 "result_count": 1,
 "path": [
 "v3",
 "reviews",
 "google",
 "task_get",
 "04011058-0696-0199-0000-2196151a15cb"
 ],
 "data": {
 "api": "reviews",
 "function": "task_get",
 "se": "google"
 },
 "result": [
 {
 "keyword": "coffee shop near me",
 "type": "reviews_google",
 "se_domain": "google.com",
 "location_code": 2840,
 "language_code": "en",
 "check_url": "https://www.google.com/search?q=coffee+shop+near+me",
 "datetime": "2019-11-15 12:57:46 +00:00",
 "title": "Example Coffee",
 "sub_title": "123 Main St, City",
 "rating": {
 "rating_type": "Max5",
 "value": 4.6,
 "votes_count": 128,
 "rating_max": 5
 },
 "feature_id": "0x89c259af12345678:0x1234567890abcdef",
 "place_id": "/html[1]/body[1]/div[3]/div[2]",
 "cid": "1234567890123456789",
 "reviews_count": 128,
 "items_count": 2,
 "items": [
 {
 "type": "google_reviews_search",
 "rank_group": 1,
 "rank_absolute": 1,
 "position": "right",
 "xpath": "/html[1]/body[1]/div[3]/div[2]/div[1]",
 "review_text": "Great coffee and friendly staff.",
 "time_ago": "2 months ago",
 "timestamp": "2019-11-15 12:57:46 +00:00",
 "rating": {
 "rating_type": "Max5",
 "value": 5,
 "votes_count": 3,
 "rating_max": 5
 },
 "reviews_count": 14,
 "photos_count": 6,
 "local_guide": true,
 "profile_name": "John D.",
 "profile_url": "https://example.com/profile/john",
 "profile_image_url": "https://example.com/profile/john.jpg",
 "owner_answer": "Thank you for your feedback!",
 "owner_time_ago": "1 month ago"
 },
 {
 "type": "google_reviews_search",
 "rank_group": 2,
 "rank_absolute": 2,
 "position": "right",
 "xpath": "/html[1]/body[1]/div[3]/div[2]/div[2]",
 "review_text": "Nice place but a bit crowded.",
 "time_ago": "3 months ago",
 "timestamp": "2019-10-20 08:30:00 +00:00",
 "rating": {
 "rating_type": "Max5",
 "value": 4,
 "votes_count": 1,
 "rating_max": 5
 },
 "reviews_count": 8,
 "photos_count": 2,
 "local_guide": false,
 "profile_name": "Alice W.",
 "profile_url": "https://example.com/profile/alice",
 "profile_image_url": "https://example.com/profile/alice.jpg",
 "owner_answer": "Thanks for visiting us!",
 "owner_time_ago": "2 months ago"
 }
 ]
 }
 ]
 }
 ]
}

常见状态与错误处理 ​

状态码范围/值含义处理建议
20000请求成功正常解析结果。
10000-60000任务级状态码范围按任务状态分别处理成功、处理中、参数错误或系统错误。
>= 40000通常表示错误记录 status_message，结合 /v3/appendix/errors 做重试或人工排查。

建议重点处理以下：

  • 顶层 status_code 成功，但 tasks[].status_code 失败
  • result 为空，说明任务可能尚未完成或无可用数据
  • tasks_ready 已返回任务，但结果拉取时单个任务失败
  • 评论数量较少时，可检查任务创建时是否设置了足够的 depth

使用说明 ​

  • 本接口只用于获取已创建任务的结果
  • 若要获取更多评论，应在创建任务时提高 depth
  • cid 可用于后续更的评论数据采集
  • 建议将 check_url 保存到业务系统中，便于质检和人工复核

实用场景 ​

  • 监控门店口碑：按门店维度批量拉取评论结果，快速掌握评分、评论量和负面反馈变化。
  • 识别差评主题：提取 review_text 与评分字段，分析服务、环境、价格等高频负面问题，指导运营整改。
  • 跟踪商家回复率：利用 owner_answer 和 owner_time_ago 评估门店是否及时回复评论，提升本地商户信誉管理水平。
  • 构建竞品对比看板：对比不同商户的 rating、reviews_count、本地向导占比等指标，区域竞争分析。
  • 质检评论采集结果：通过 check_url 回查搜索页，验证位置、语言和商户匹是否准确，降低数据偏差风险。

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

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