获取已完成的 Hotel Info 任务列表

接口说明

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

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

如需了解任务完成机制以及已完成任务列表的获取方式，可参考帮助文档。

注意： 由于平台 API 的队列机制，已完成任务列表会有轻微延迟。 如果你的系统需要每分钟采集 1000 个任务，建议优使用 pingback/postback 方式在回调失败时再使用 Tasks Ready 接口补拉失败任务的 ID。

---

请求地址

获取 Google Hotel Info 已完成任务列表：

GET /v3/business_data/google/hotel_info/tasks_ready

完整请求地址：

https://api.seermartech.cn/v3/business_data/google/hotel_info/tasks_ready

此外，该能力也支持以下通用路径：

• 指定搜索引擎获取已完成任务： GET /v3/business_data/$se/tasks_ready
• 获取 Business Data部已完成任务： GET /v3/business_data/tasks_ready

---

计费与限制

• 获取已完成任务列表不额外收费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 每次调用最多返回过去 3 天已完成的 1000 个任务
• 每分钟最多可发起 20 次 API 调用
• 任务会一直保留在列表中，直到你成功获取结果
• 已被拉取的任务不会再次出现在列表中
• 完成后 3 天未拉取的任务，也不会再出现在列表中

postback_url 的行为

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

只有当回调到你服务器的请求失败时，该任务才可能出现在列表中，例如：

• 你的服务器请求处理失败
• 返回的 HTTP 状态码 小于 200
• 返回的 HTTP 状态码 大于 300

---

响应结构

接口返回 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	请求路径
data	object	请求 URL 中传递的参数
result	array	已完成任务列表

tasks[].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_info/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_info/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/business_data/google/hotel_info/tasks_ready",
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
}).then((response) => {
 console.log(response.data);
}).catch((error) => {
 console.error(error);
});

---

响应示例

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

说明：示例中的响应片段存在省略与格式截断，这里按标准 JSON 结构整理展示。返回字段以接口响应为准。

---

错误处理

你可以通过以下字段判断请求是否成功：

• 顶层 status_code：判断整个接口调用状态
• tasks[].status_code：判断单个任务是否成功
• tasks_error：返回错误任务数量

完整错误码与状态说明请参考：

• /v3/appendix/errors

---

使用建议

1. 定时轮询本接口，获取最近已完成但未获取结果的任务 ID
2. 读取 tasks[].result[].endpoint，调用对应 Task GET 接口获取详细结果
3. 如已 postback_url，本接口更适合作为回调失败补偿机制
4. 高并发场景下，优使用回调方式，因列表延迟影响实时性

实用场景

• 补拉失败回调任务：当 postback 回调失败时，快速找回未成功通知的任务 ID，数据遗漏。
• 批量拉取信息结果：定时获取已完成任务列表，再统一调用结果接口，提升批处理效率。
• 监控任务处理进度：通过已完成任务数量与提交时间，评估信息采集链路的执行状态。
• 对账任务消耗与产出：结合返回的 cost、result_count 和任务 ID，核对任务完成量与成本。
• 构建容错采集流程：将 Tasks Ready 作为异步任务系统的底机制，降低因回调异常导致的数据丢失风险。