SeerMarTech API 文档

主题

按任务 ID 获取 Google Extended Reviews 结果 ​

本接口使用 GET 方法，通过任务 ID 获取 Google Extended Reviews 任务结果。

接口路径：

text
GET https://api.seermartech.cn/v3/business_data/google/extended_reviews/task_get/$id

返回结果与任务提交时指定的本地商家名称、搜索引擎、位置和语言。本平台会尽可能精准地模拟指定的位置和搜索环境，使返回结果与任务提交时对应参数下的搜索结果保持一致。

你可以访问响应中的 check_url，并使用无痕模式打开，以验证结果的性。系统不会考虑用户偏好、搜索历史及个性化因素，因此这些因素不会反映在返回结果中。

计费说明 ​

  • 在创建任务时计费。
  • 任务创建后 30 天可查询任务结果。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
  • 沙盒接口不计费。

请求参数 ​

参数通过 URL 路径传递。

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

示例：

text
https://api.seermartech.cn/v3/business_data/google/extended_reviews/task_get/04011058-0696-0199-0000-2196151a15cb

返回结果 ​

接口返回 JSON 数据，顶层 tasks 数组。

顶层响应字段 ​

字段名类型说明
versionstring当前 API 版本。
status_codeinteger通用状态码。成功通常为 20000。
status_messagestring通用状态说明。
timestring接口执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数量。
tasks_errorintegertasks 数组中返回错误的任务数量。
tasksarray任务结果数组。

tasks 对象字段 ​

字段名类型说明
idstring任务唯一标识符，UUID 格式。
status_codeinteger任务状态码，通常为 10000 至 60000。
status_messagestring任务状态说明。
timestring任务执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。
patharray请求路径信息。
dataobject创建任务时提交的参数。
resultarray任务结果数组。

tasks.data 字段 ​

data 通常创建任务时提交的原始参数，例如：

字段名类型说明
se_typestring搜索结果类型，例如 extended_reviews。
sestring搜索引擎，例如 google。
apistringAPI 类型，例如 business_data。
functionstring功能名称，例如 extended_reviews。
location_namestring搜索位置名称。
language_namestring搜索语言名称。
cidstringGoogle 商家 CID。
devicestring设备类型，例如 desktop。
osstring操作系统，例如 windows。

result 字段 ​

Extended Reviews 结果字段 ​

字段名类型说明
keywordstring创建任务时提交的。返回时会对编码进行解码，+ 会被解码为空格。
typestring搜索结果类型。
se_domainstring搜索引擎域名。
location_codeinteger位置代码。
language_codestring语言代码。
check_urlstring对应搜索结果页面的直接 URL，可用于验证结果准确性。
datetimestring获取结果的日期和时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
titlestringSERP 中 Reviews素的标题，即收集评论的本地商家名称。
sub_titlestringReviews素的副标题，例如商家地址等补信息。
ratingobject对应本地商家的总体评分。
feature_idstringSERP 中 Reviews素的唯一标识符。
place_idstringGoogle 分给商家位置的唯一标识符。
cidstringGoogle 定义的商家客户端 ID，本地商家的唯一标识符。
reviews_countinteger商家的评论总数。
items_countinteger当前结果中返回的评论数量。可在创建任务时增大 depth 获取更多评论。
itemsarray找到的评论列表。

result.rating 字段 ​

字段名类型说明
rating_typestring评分类型，可选值 Max5、Percents、CustomMax。
valuefloat所有评论的平均评分。
votes_countinteger评分票数。
rating_maxinteger对应评分类型的最大值。

items 评论字段 ​

字段名类型说明
typestring评论类型，通常为 google_extended_reviews_search。
rank_groupinteger在相同 type 结果组中的排名。不同类型不会计该排名。
rank_absoluteinteger评论在评论列表中的绝对排名。
positionstring评论在 SERP 中的对齐位置，通常为 right 或 left。
xpathstring评论在页面中的 XPath。
review_textstring评论。
original_review_textstring评论原文，不经过自动翻译。
time_agostring评论发布时间的相对时间，例如 2 weeks ago。
timestampstring评论发布时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
ratingobject评论提交的评分。
reviews_countinteger评论提交的评论总数。
photos_countinteger评论提交的总数。
local_guideboolean是否 Local Guide 身份。
profile_namestring评论资料名称。
profile_urlstring评论资料页 URL。
review_urlstring评论页 URL。
profile_image_urlstring评论头像 URL。
owner_answerstring商家对该评论的回复。
original_owner_answerstring商家回复原文，不经过自动翻译。
owner_time_agostring商家回复的相对发布时间。
owner_timestampstring商家回复时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
review_idstringGoogle 上该评论的唯一标识符。
imagesarray评论提交的图片。
review_highlightsarray评论重点，被提及的评价维度及评价。
sourceobject评论来源信息。

items.rating 字段 ​

字段名类型说明
rating_typestring评分类型，可选值为 Max5 或 CustomMax。
valuefloat评论评分值。
votes_countinteger该评论获得的投票或反馈数量。
rating_maxinteger评分最大值。Max5 类型的最大值为 5。

items.images 字段 ​

字段名类型说明
typestring图片类型，固定为 images_element。
altstring图片的替代文本。
image_urlstring评论图片 URL。

items.review_highlights 字段 ​

字段名类型说明
featurestring被评价的功能或特征。
assessmentstring对该功能或特征的评价。

items.source 字段 ​

字段名类型说明
titlestring发布评论的平台名称。
imagestring评论来源平台的图片。
domainstring评论来源平台的域名。

沙盒测试 ​

可以使用以下沙盒任务 ID 查看完整字段结构。沙盒数据为模拟数据，不会产生费用：

text
https://sandbox.seermartech.cn/v3/business_data/google/extended_reviews/task_get/00000000-0000-0000-0000-000000000000

请求示例 ​

cURL ​

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

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

Python ​

python
import requests

task_id = "05211333-2692-0298-0000-047fc45592ce"
url = (
    "https://api.seermartech.cn/v3/business_data/google/"
    f"extended_reviews/task_get/{task_id}"
)

response = requests.get(
    url,
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
)

response.raise_for_status()
data = response.json()

if data.get("status_code") == 20000:
    for task in data.get("tasks", []):
        if task.get("status_code", 0) >= 40000:
            print(
                f"任务失败：{task.get('status_code')} "
                f"{task.get('status_message')}"
            )
        else:
            print(task.get("result"))
else:
    print(
        f"请求失败：{data.get('status_code')} "
        f"{data.get('status_message')}"
    )

TypeScript ​

typescript
import axios from "axios";

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

async function getTaskResult() {
  const response = await axios.get(
    `https://api.seermartech.cn/v3/business_data/google/extended_reviews/task_get/${taskId}`,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  );

  const data = response.data;

  if (data.status_code !== 20000) {
    throw new Error(
      `请求失败：${data.status_code} ${data.status_message}`
    );
  }

  for (const task of data.tasks ?? []) {
    if (task.status_code >= 40000 || !task.result) {
      console.error(
        `任务失败：${task.status_code} ${task.status_message}`
      );
    } else {
      console.log("任务结果：", task.result);
    }
  }
}

getTaskResult().catch(console.error);

响应示例 ​

以下示例展示一个商家评分和评论明细的成功响应：

json
{
  "version": "0.1.20241028",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0798 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "04011058-0696-0199-0000-2196151a15cb",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0450 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "business_data",
        "google",
        "extended_reviews",
        "task_get",
        "04011058-0696-0199-0000-2196151a15cb"
      ],
      "data": {
        "se_type": "extended_reviews",
        "se": "google",
        "api": "business_data",
        "function": "extended_reviews",
        "location_name": "London,England,United Kingdom",
        "language_name": "english",
        "cid": "17626775537598922320",
        "device": "desktop",
        "os": "windows"
      },
      "result": [
        {
          "keyword": "Travelodge Covent Garden",
          "type": "google_extended_reviews_search",
          "se_domain": "google.com",
          "location_code": 1006886,
          "language_code": "en",
          "check_url": "https://www.google.com/search?q=Travelodge+Covent+Garden",
          "datetime": "2024-10-26 09:20:15 +00:00",
          "title": "Travelodge Covent Garden",
          "sub_title": "London, England, United Kingdom",
          "rating": {
            "rating_type": "Max5",
            "value": 4.1,
            "votes_count": null,
            "rating_max": 5
          },
          "feature_id": "feature-example",
          "place_id": "ChIJexample",
          "cid": "17626775537598922320",
          "reviews_count": 1250,
          "items_count": 1,
          "items": [
            {
              "type": "google_extended_reviews_search",
              "rank_group": 1,
              "rank_absolute": 1,
              "position": "left",
              "xpath": null,
              "review_text": "The room was clean and comfortable.",
              "original_review_text": null,
              "time_ago": "3 days ago",
              "timestamp": "2024-10-26 09:20:15 +00:00",
              "rating": {
                "rating_type": "Max5",
                "value": 5,
                "votes_count": null,
                "rating_max": 5
              },
              "reviews_count": 78,
              "photos_count": 3,
              "local_guide": false,
              "profile_name": "Example User",
              "profile_url": "https://www.google.com/maps/contrib/example/reviews",
              "review_url": "https://www.google.com/maps/reviews/data=example",
              "profile_image_url": "https://lh3.googleusercontent.com/example",
              "owner_answer": null,
              "original_owner_answer": null,
              "owner_time_ago": null,
              "owner_timestamp": null,
              "review_id": "ChdDSUhNMG9nS0VJQ0FnSUNYdE9yeXFnRRAB",
              "images": [],
              "review_highlights": [
                {
                  "feature": "Cleanliness",
                  "assessment": "Positive"
                }
              ],
              "source": {
                "title": "Google",
                "image": "https://www.gstatic.com/images/branding/product/1x/googleg_48dp.png",
                "domain": "www.google.com"
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理 ​

建议根据顶层和任务级别的状态字段分别处理异常：

  • status_code = 20000：请求或任务成功。
  • status_code >= 40000：请求或任务处理失败，应结合 status_message 定位原因。
  • 即使顶层请求成功，也应继续检查 tasks[].status_code，因为单个任务可能独立失败。
  • 当 result 为空或不存在时，不应继续解析评论数据。

完整错误码请参考本平台错误码文档。

实用场景 ​

  • 采集本地商家评论：获取指定商家在 Google 搜索结果中的评论、评分和发布时间，为本地 SEO 口碑分析提供数据。
  • 监测竞品评价变化：定期查询竞争商家的评论与评分，识别服务、位置、价格等高频评价维度，支持竞品策略调整。
  • 分析评论主题与感：结合 review_text、review_highlights 和评分字段提取用户点，优化商家页面和服务卖点。
  • 跟踪商家回复表现：分析 owner_answer、回复时间及评论评分，评估商家对负面反馈的响应及时性和运营质量。
  • 构建本地排名与口碑报表：结合 place_id、cid、总体评分、评论数量和评论明细，生成多门店 SEO 口碑监控报表。

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

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