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

接口说明

该接口用于获取已执行完成但尚未被获取结果的任务列表。

如果你在创建任务时使用的是标准方式，且没有指定 postback_url，可以通过本接口获取所有已完成任务的 id，随后再调用对应的 Task GET 结果接口拉取详细数据。

接口路径：

GET /v3/keywords_data/google_trends/explore/tasks_ready

完整请求地址：

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

使用说明

• 本接口返回的是最近三天完成、但尚未被获取结果的任务
• 每次请求最多返回 1000 个任务
• 接口调用频率上限为 20 次/分钟
• 已经被拉取过结果的任务，不会继续出现在列表中
• 任务完成后若 3 天未拉取，也不会再出现在列表中
• 如果任务提交时设置了 postback_url，该任务通常不会出现在已完成任务列表中
• 只有当回调推送失败时，任务才可能出现在本列表中，例如你的服务端返回的 HTTP 状态码 小于 200 或大于 300

注意：由于平台 API 的任务完成队列存在短暂延迟，高并发场景下可能无法做到实时获取。 如果你的系统需要以每分钟 1000 个任务的规模持续接收完成通知，建议优使用回调机制（pingback/postback），而将本接口用于补拉回调失败任务的 ID。

计费说明

获取已完成任务列表不收费。

响应中的 cost 通常为 0，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求示例

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"

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)
print(response.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);
 });

响应结构

接口返回 JSON 数据，顶层 tasks 数组每个表示一次接口任务。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	接口通用状态码
status_message	string	接口通用状态信息
time	string	请求处理耗时，单位秒
cost	float	本次请求总成本，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数
tasks	array	任务数组

错误码及状态消息请参考 /v3/appendix/errors。 建议在接时对异常状态和错误返回做好健壮处理。

tasks[] 字段

字段	类型	说明
id	string	当前请求任务 ID，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务状态说明
time	string	任务执行耗时，单位秒
cost	float	该任务成本，单位 USD
result_count	integer	result 数组中的数量
path	array	请求路径信息
data	object	URL 路径中传的参数
result	array	已完成任务列表

tasks[].result[] 字段

字段	类型	说明
id	string	已完成任务的任务 ID，UUID 格式
se	string	创建任务时指定的搜索引擎
function	string	任务类型
date_posted	string	任务提交时间，UTC 格式
tag	string	用户自定义任务标识
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": "2c741d2f-9b67-4f9d-9f4b-1a8d6f0d6abc",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0213 sec.",
 "cost": 0,
 "result_count": 2,
 "path": [
 "v3",
 "keywords_data",
 "google_trends",
 "explore",
 "tasks_ready"
 ],
 "data": {
 "api": "keywords_data",
 "function": "explore",
 "se": "google"
 },
 "result": [
 {
 "id": "7f9d9c73-0c47-4b28-b31a-2f9fb8d4e001",
 "se": "google",
 "function": "explore",
 "date_posted": "2024-01-10 08:15:27 +00:00",
 "tag": "trend-batch-001",
 "endpoint": "/v3/keywords_data/google_trends/explore/task_get/7f9d9c73-0c47-4b28-b31a-2f9fb8d4e001"
 },
 {
 "id": "7f9d9c73-0c47-4b28-b31a-2f9fb8d4e002",
 "se": "google",
 "function": "explore",
 "date_posted": "2024-01-10 08:16:02 +00:00",
 "tag": "trend-batch-002",
 "endpoint": "/v3/keywords_data/google_trends/explore/task_get/7f9d9c73-0c47-4b28-b31a-2f9fb8d4e002"
 }
 ]
 }
 ]
}

结果拉取方式

通过本接口拿到 result[].id 或 result[].endpoint 后，可继续调用对应的结果获取接口拉取任务。

型流程如下：

1. 提交 Google Trends Explore 任务
2. 轮询 /v3/keywords_data/google_trends/explore/tasks_ready
3. 获取已完成任务的 id
4. 调用对应的 Task GET 接口获取结果

状态与异常处理建议

• 当顶层 status_code = 20000 时，表示请求成功
• 当 tasks_error > 0 时，说明部分任务返回异常，需要逐条检查 tasks[]
• 若 result_count = 0，表示当前没有可拉取的已完成任务
• 若你依赖回调机制但发现任务出现在本接口中，应重点检查回调地址可用性以及服务端返回码是否为 2xx

实用场景

• 轮询已完成任务：批量获取尚未获取结果的 Google Trends Explore 任务 ID，逐个猜测任务完成状态。
• 补拉回调失败数据：当 postback_url 推送失败时，用本接口找出漏收任务并重新获取结果，减少数据丢失。
• 构建任务消费队列：将已完成任务统一汇总到处理队列，再分发给下游分析模块，提高趋势数据处理效率。
• 监控任务完成率：结合 date_posted、tag 和结果列表，检查哪些趋势任务已完成但尚未被业务系统消费。
• 恢复中断任务流程：在采集程序异常重启后，重新扫描最近三天未拉取任务，快速恢复趋势分析链路。