获取 Google Trends Explore 已完成任务列表

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

/v3/keywords_data/google_trends/explore/tasks_ready

用于获取已完成但尚未领取的任务列表。通过标准任务提交方式创建任务且未设置 postback_url 时，可调用本接口获取所有已完成任务的 id，再通过对应的任务结果获取接口领取任务结果。

如果任务设置了 postback_url，正常不会出现在本接口返回的列表中。当平台向您的服务器推送失败，且服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能出现在列表中。

> 注意：由于系统架构限制，已完成任务队列可能存在少量延迟。对于每分钟需要领取 1000 个任务的高并发场景，建议优使用回调（pingback/postback）机制，并将本接口用于获取回调失败任务的 ID。

请求信息

• 请求方法：GET
• 请求路径：/v3/keywords_data/google_trends/explore/tasks_ready
• **请求体：**无
• **认证方式：**Bearer Token
• **参考价：**本接口获取任务列表不收费
• **计费说明：**扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求限制

• 每分钟最多调用 20 次。
• 每次调用最多返回最近 3 天完成的 1000 个任务。
• 任务在被领取前会持续保留在列表中。
• 已领取的任务不会再次返回。
• 任务完成后 3 天仍未领取的，不会出现在列表中。

请求示例

cURL

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

TypeScript

import axios from "axios";

axios({
  method: "get",
  url: "https://api.seermartech.cn/v3/keywords_data/google_trends/explore/tasks_ready",
  headers: {
    Authorization: "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
})
  .then((response) => {
    // 处理已完成任务列表
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

Python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/google_trends/explore/tasks_ready"

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

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

if data.get("status_code") == 20000:
    # 遍历已完成任务
    for task_group in data.get("tasks", []):
        for task in task_group.get("result", []):
            print(task.get("id"))
else:
    print(
        "请求失败，错误码：{}，错误信息：{}".format(
            data.get("status_code"),
            data.get("status_message"),
        )
    )

返回结果

接口返回 JSON 对象 tasks 数组任务列表信息。

顶层字段

字段	类型	说明
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	请求路径信息
data	object	创建任务时传的请求参数
result	array	已完成任务结果数组

result 字段

字段	类型	说明
id	string	已完成任务的任务 ID，采用 UUID 格式
se	string	创建任务时指定的搜索引擎
function	string	任务类型
date_posted	string	任务提交时间，使用 UTC 时间格式
endpoint	string	用于领取该任务结果的接口路径

响应示例

{
  "version": "3.20191128",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1927 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "7f5c8a0e-7f0e-4e6f-8e31-123456789abc",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0150 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "keywords_data",
        "google_trends",
        "explore",
        "tasks_ready"
      ],
      "data": {
        "api": "keywords_data",
        "function": "explore",
        "se": "google"
      },
      "result": [
        {
          "id": "7f5c8a0e-7f0e-4e6f-8e31-123456789abc",
          "se": "google",
          "function": "explore",
          "date_posted": "2024-01-15 08:30:00 +00:00",
          "endpoint": "/v3/keywords_data/google_trends/explore/task_get"
        }
      ]
    }
  ]
}

处理建议

1. 使用任务 id 调用响应中的 endpoint，领取对应任务结果。
2. 成功领取后，不要重复处理同一任务，业务侧重复库。
3. 为 status_code 和 status_message 增加异常处理逻辑。
4. 对于高吞吐任务，优使用 postback_url 接收任务完成通知。
5. 定期调用本接口理回调失败任务，任务 3 天后无法领取。

实用场景

• 轮询已完成任务：批量获取 Google Trends 探索任务 ID，并继续领取趋势结果，提升研究流程的自动化程度。
• 补偿回调失败任务：发现未成功推送到业务服务器的任务，趋势数据出现缺失。
• 构建任务调度队列：任务完成状态批量拉取任务，统一安排结果解析、库和后续分析。
• 监控任务处理：结合 tasks_count、tasks_error 和状态码统计任务完成质量，及时定位接口或业务异常。
• 支撑周期性分析：定时获取已完成的趋势任务，为选题、季节性需求判断和 SEO 选词提供数据。