获取 Google Extended Reviews 已完成任务列表

GET /v3/business_data/google/extended_reviews/tasks_ready

本接口使用 GET 方法，请求路径为：

/v3/business_data/google/extended_reviews/tasks_ready

用于获取已完成但尚未领取的 Google Extended Reviews 任务列表。获取任务 ID 后，可通过对应的任务结果接口查询完整结果。

如果创建任务时未设置 postback_url，可使用本接口轮询已完成任务。对于每分钟需要领取 1,000 个任务的高并发场景，建议优使用回调通知机制，并将本接口用于补偿查询回调失败的任务。

> 注意：由于任务完成队列存在少量更新延迟，高并发场景下可能无法立即获取刚完成的任务。

接口地址

http

GET https://api.seermartech.cn/v3/business_data/google/extended_reviews/tasks_ready

也可以使用通用路径获取指定搜索引擎或 Business Data API 的已完成任务：

http

GET https://api.seermartech.cn/v3/business_data/$se/tasks_ready
GET https://api.seermartech.cn/v3/business_data/tasks_ready

，$se 为搜索引擎名称。本接口支持：

google

计费与调用限制

获取已完成任务列表不收取费用。
每个已完成任务在被领取前会持续保留在列表中。
每分钟最多调用 20 次。
每次调用最多返回过去 3 天完成的 1,000 个任务。
已被领取的任务不会再次出现在列表中。
完成后 3 天仍未领取的任务将从列表中移除。
如果创建任务时设置了 postback_url，任务通常不会出现在本列表中。
当向回调地址发送请求失败，且目标服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能重新出现在列表中。

本接口本身不产生任务费用；扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

响应字段

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	请求级状态码。完整状态码列表请参 `/v3/appendix/errors`
`status_message`	string	请求级说明信息
`time`	string	接口执行耗时，单位为秒
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量
`tasks`	array	已完成任务列表

`tasks` 数组字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，通常在 `10000` 至 `60000` 范围。完整列表请参 `/v3/appendix/errors`
`status_message`	string	任务状态说明
`time`	string	任务执行耗时，单位为秒
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量
`path`	array	用于获取任务结果的 URL 路径信息
`data`	object	创建任务时传的请求参数及接口信息
`result`	array	已完成任务的摘要结果

`tasks[].result` 数组字段

字段	类型	说明
`id`	string	已完成任务的唯一标识，UUID 格式
`se`	string	创建任务时指定的搜索引擎，取值为 `google`
`se_type`	string	搜索引擎数据类型
`date_posted`	string	任务提交时间，UTC 格式
`tag`	string	用户自定义任务标识
`endpoint`	string	用于获取任务完整结果的接口路径

请求示例

cURL

bash

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

Python

python

import requests

url = "https://api.seermartech.cn/v3/business_data/google/extended_reviews/tasks_ready"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

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

if response.status_code == 200:
    data = response.json()
    if data.get("status_code") == 20000:
        print(data)
        # 在此处理已完成任务列表
    else:
        print(
            "API 错误：代码 %s，信息 %s"
            % (data.get("status_code"), data.get("status_message"))
        )
else:
    print("HTTP 错误：", response.status_code)

TypeScript

typescript

import axios from "axios";

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

    const result = response.data;

    if (result.status_code === 20000) {
      console.log(result);
      // 在此处理已完成任务列表
    } else {
      console.error(
        `API 错误：代码 ${result.status_code}，信息 ${result.status_message}`
      );
    }
  } catch (error) {
    console.error("请求失败：", error);
  }
}

getTasksReady();

响应示例

json

{
  "version": "0.1.20241028",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1096 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "2f6e8b3a-1c2d-4d8f-9a10-123456789abc",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0842 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "business_data",
        "google",
        "extended_reviews",
        "task_get"
      ],
      "data": {
        "se_type": "extended_reviews",
        "se": "google",
        "api": "business_data",
        "function": "extended_reviews"
      },
      "result": [
        {
          "id": "2f6e8b3a-1c2d-4d8f-9a10-123456789abc",
          "se": "google",
          "se_type": "extended_reviews",
          "date_posted": "2024-10-28 10:30:00 +00:00",
          "tag": "review-task-001",
          "endpoint": "/v3/business_data/google/extended_reviews/task_get"
        }
      ]
    }
  ]
}

获取 id 后，请调用响应中 endpoint 指定的任务结果接口，查询该任务的完整数据。

错误处理

建议对以下字段进行统一处理：

读取顶层 status_code，判断本次请求是否成功。
检查 tasks_error，确认返回列表中是否失败任务。
读取任务级 status_code 和 status_message，定位单个任务的问题。
对非 20000 的状态码进行记录、重试或告警。

完整状态码和错误说明请参 /v3/appendix/errors。

实用场景

轮询已完成任务并批量领取结果：定时获取任务 ID，减少逐个查询任务状态的请求次数，提高评论数据采集效率。
补偿回调通知失败的任务：定期检查未成功推送的任务，因业务服务器短暂异常造成数据遗漏。
构建评论数据同步队列：根据 date_posted、tag 和任务 ID 维护增量同步记录，支持 SEO 舆数据的稳定库。
监控任务处理延迟：结合任务完成时间和领取时间统计处理延迟，及时发现采集链路或回调服务异常。

获取 Google Extended Reviews 已完成任务列表 ​

接口地址 ​

计费与调用限制 ​

响应字段 ​

顶层字段 ​

tasks 数组字段 ​

tasks[].result 数组字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

错误处理 ​

实用场景 ​