获取 Google Hotel Searches 已完成任务列表

接口说明

Tasks Ready 接口用于获取已经执行完成、但尚未被领取结果的任务列表。

如果你没有 postback_url，可以通过本接口批量获取已完成任务的 id，再调用对应的 Task GET 接口拉取任务结果。

请求地址

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

容路径

你也可以按搜索引擎或业务维度使用以下容路径：

GET /v3/business_data/$se/tasks_ready
GET /v3/business_data/tasks_ready

$se 为搜索引擎名称。当前该接口场景下通常为 google。

使用说明

由于平台 API 架构特性，已完成任务队列的更新会有轻微延迟。对于高并发场景，如果你的系统需要每分钟处理 1000 个任务，建议优使用 pingback / postback 机制，本接口更适合：

• 轮询获取普通已完成任务
• 补偿获取 postback 投递失败的任务 ID

重要规则

• 每次调用最多返回最近 3 天已完成的 1000 个任务
• 每分钟最多调用 20 次
• 任务在被成功领取结果前，会一直保留在列表中
• 已经领取过结果的任务，不会再次出现在列表中
• 完成后 3 天未领取 的任务，不会继续保留在列表中

postback_url

如果你在创建任务时指定了 postback_url，该任务通常不会出现在已完成任务列表中。

当以下发生时，任务才可能重新出现在列表里：

• 向你的服务器发送 postback 请求失败
• 你的服务器返回的 HTTP 状态码 小于 200 或大于 300

计费

获取已完成任务列表不会产生额外费用。

• 本接口参考价约 ¥0.0000 / 次
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

响应结构

接口返回 JSON 数据，顶层 tasks 数组，每个对应一次接口任务结果。

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	接口总体状态码，完整列表见 /v3/appendix/errors
status_message	string	接口总体状态信息，完整列表见 /v3/appendix/errors
time	string	执行耗时，单位秒
cost	float	本次请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务数组

建议在接时对异常状态和错误码建立完整处理机制。

tasks 数组字段

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

result 数组字段

字段名	类型	说明
id	string	已完成任务的任务 ID，UUID 格式
se	string	创建任务时指定的搜索引擎，当前可为 google
se_type	string	搜索引擎类型
date_posted	string	任务提交时间，UTC 格式
tag	string	用户自定义任务标识
endpoint	string	用于拉取该任务结果的接口地址

请求示例

cURL

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

Python

import requests

url = "https://api.seermartech.cn/v3/business_data/google/hotel_searches/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:
 print(data)
else:
 print(f"error. Code: {data.get('status_code')} Message: {data.get('status_message')}")

TypeScript

import axios from "axios";

// 获取已完成但尚未领取的 Hotel Searches 任务列表
axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/business_data/google/hotel_searches/tasks_ready",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then(function (response) {
 // 返回结果
 console.log(response.data);
 })
 .catch(function (error) {
 console.error(error);
 });

响应示例

返回的 JSON 结构大致如下：

{
 "version": "0.1.20210430",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1465 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "se_type": "hotels",
 "se": "google",
 "api": "business_data",
 "function": "hotel_searches"
 },
 "result": []
 }
 ]
}

对接建议

型调用流程如下：

1. 提交 Hotel Searches 采集任务
2. 轮询 /v3/business_data/google/hotel_searches/tasks_ready 获取已完成任务 ID
3. 从返回的 result[].endpoint 或任务 ID 调用对应 Task GET 接口拉取明细结果
4. 成功处理后，不再重复领取同一任务结果

如果你的业务对实时性要求较高，或任务量极大，建议优启用 postback 机制，并将本接口作为失败补偿通道。

常见状态处理

• 20000：请求成功
• 非 20000：表示请求或任务存在异常，应结合 status_message 和 /v3/appendix/errors 排查

建议至少处理以下：

• 鉴权失败
• 请求频率限
• 任务结果为空
• postback 失败后的补偿拉取 -过 3 天未领取导致任务不再返回

实用场景

• 轮询已完成搜索任务：在未启用回调机制时，定时获取最新完成任务，保证采集链路持续运转。
• 补偿拉取回调失败任务：当业务系统未成功接收 postback 时，重新找回可领取任务 ID，结果丢失。
• 批量调度结果抓取：统一获取完成任务单，再分发给下游 Worker 拉取，提升大规模采集效率。
• 追踪任务处理状态：结合 tag、date_posted 与 endpoint，核对任务是否按预期完成并结果领取流程。
• 理积压未领取结果：定时检查最近 3 天尚未消费的任务，因时未领取而丢失数据。