reviews/tasks_ready

获取 Google Reviews 已完成任务

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

http

GET https://api.seermartech.cn/v3/reviews/google/tasks_ready

本接口用于获取已完成但尚未领取结果的 Google Reviews 任务列表。

如果创建任务时未 postback_url，可以通过本接口获取所有符合条件的已完成任务 ID，再使用任务结果获取接口领取结果。

计费与限制

获取已完成任务列表不产生额外费用。
每个任务在被成功领取前都会保留在列表中。
每分钟最多调用 20 次。
每次调用最多返回最近 3 天完成的 1000 个任务。
已经领取结果的任务不会再次出现在列表中。
任务完成后 3 天仍未领取的，也不会出现在列表中。
如果任务了 postback_url，正常不会出现在本列表中。
当向回调地址发送请求失败，且服务端返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能重新出现在已完成任务列表中。

接口返回 JSON 数据 tasks 数组及每个任务的详细信息。

请求示例

cURL

bash

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

Python

python

import requests

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

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

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

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

TypeScript

typescript

import axios from "axios";

async function getReadyTasks() {
  try {
    const response = await axios.get(
      "https://api.seermartech.cn/v3/reviews/google/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(
        `接口错误：代码 ${result.status_code}，消息：${result.status_message}`
      );
    }
  } catch (error) {
    console.error("请求失败：", error);
  }
}

getReadyTasks();

响应字段

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	接口整体状态码
`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`
`status_message`	string	任务状态说明
`time`	string	任务执行耗时，单位为秒
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的结果数量
`path`	array	请求 URL 路径信息
`data`	array	创建任务时传的 URL 参数
`result`	array	任务结果数组

`tasks.result` 字段

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

响应示例

json

{
  "version": "0.1.20200325",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1486 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "32f5d1c2-7b6a-4c2f-9f2a-123456789abc",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1200 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "reviews",
        "google",
        "tasks_ready"
      ],
      "data": [
        {
          "api": "reviews",
          "function": "tasks_ready",
          "se": "google"
        }
      ],
      "result": [
        {
          "id": "32f5d1c2-7b6a-4c2f-9f2a-123456789abc",
          "se": "google",
          "se_type": "reviews",
          "date_posted": "2024-01-15 08:30:00 +00:00",
          "tag": "restaurant-review-task-001",
          "endpoint": "/v3/reviews/google/task_get/32f5d1c2-7b6a-4c2f-9f2a-123456789abc"
        }
      ]
    }
  ]
}

状态码与异常处理

建议在业务系统中同时处理以下信息：

HTTP 状态码，用于判断网络层和服务层请求是否成功。
顶层 status_code，用于判断本次 API 调用是否成功。
tasks_error，用于识别任务列表中是否存在错误任务。
任务级别的 status_code 和 status_message，用于定位单个任务的问题。

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

实用场景

轮询已完成任务列表，批量发现尚未领取的评论采集任务，依赖回调服务并减少结果遗漏。
领取任务结果并写评论数据库，持续更新商家评分、评论和发布时间等 SEO 口碑数据。
补偿回调失败的任务，通过定时检查任务状态恢复异常中断的评论数据采集流程。
理保留期限仍未领取的任务，及时告警并调整任务消费频率，降低数据丢失风险。
****任务 tag 与项目或商家 ID，将已完成评论任务准确归档到对应的 SEO 监控项目。

reviews/tasks_ready ​

获取 Google Reviews 已完成任务 ​

计费与限制 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应字段 ​

顶层字段 ​

tasks 字段 ​

tasks.result 字段 ​

响应示例 ​

状态码与异常处理 ​

实用场景 ​