获取 Tripadvisor Search 已完成任务列表

接口说明

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

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

需要注意的是，由于平台 API 的任务队列存在短暂延迟，已完成任务列表不会在任务结束后立即同步更新。对于高并发场景，如果你的系统需要每分钟拉取 1000 个任务，建议优使用 pingback/postback 回调机制，并将 Tasks Ready 用于获取回调失败任务的 ID。

接口地址

获取 Tripadvisor Search 已完成任务：

GET https://api.seermartech.cn/v3/business_data/tripadvisor/search/tasks_ready

此外，本组接口也支持以下通用路径：

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

说明：在本接口中，$se 为搜索引擎名称；对于当前页面对应能力，固定为 tripadvisor。

使用限制

• 获取结果不额外收费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 每分钟最多可调用 20 次
• 每次调用最多返回 1000 个任务
• 返回最近 3 天完成且尚未被拉取的任务
• 已经成功拉取过结果的任务，不会再次出现在列表中
• 任务完成后若 3 天未拉取，将不再出现在列表中

postback_url 的行为

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

只有在以下，任务才会重新出现在本接口返回的列表中：

• 平台向你的服务器发送回调失败
• 你的服务器返回的 HTTP 状态码 小于 200 或 大于 300

响应结构

接口返回 JSON 数据，顶层 tasks 数组，用于表示本次返回的任务列表。

顶层字段说明

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

建议在接时做好状态码与异常处理逻辑，是批量轮询场景。

tasks 数组字段说明

字段	类型	说明
id	string	当前任务请求的唯一标识，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	创建任务时指定的搜索引擎；当前接口固定为 tripadvisor
se_type	string	搜索引擎类型
date_posted	string	任务提交时间，UTC 格式
tag	string	用户自定义任务标识
endpoint	string	用于拉取该任务结果的接口地址

请求示例

cURL

curl --location --request GET "https://api.seermartech.cn/v3/business_data/tripadvisor/search/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/tripadvisor/search/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";

async function getReadyTasks {
 try {
 const response = await axios.get(
 "https://api.seermartech.cn/v3/business_data/tripadvisor/search/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.log(`error. Code: ${result.status_code} Message: ${result.status_message}`);
 }
 } catch (error) {
 console.error(error);
 }
}

getReadyTasks;

响应示例

{
 "version": "0.1.20210917",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1630 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "se_type": "search",
 "se": "tripadvisor",
 "api": "business_data",
 "function": "search"
 },
 "result": []
 }
 ]
}

说明：平台原始示例中的响应有截断与排版缺失，这里按原始结构进行保留整理。响应中通常还会任务级别的 id、status_code、status_message、time、cost、result_count、path 等字段。

错误处理

你需要重点两层状态：

1. 接口级状态

• status_code
• status_message

2. 任务级状态

• tasks[].status_code
• tasks[].status_message

建议将以下纳重试或告警逻辑：

• 接口整体返回非成功状态
• tasks_error 大于 0
• 某些任务缺少 result
• 拉取频率每分钟 20 次限制
• 回调失败任务持续堆积

对接建议

• 如果任务量较小，可通过轮询 tasks_ready + 调用 Task GET 的方式获取结果
• 如果任务量较大，建议优使用回调机制
• 如果已回调，可定期调用本接口补偿回调失败的数据
• 建议结合 tag 字段建立业务侧任务映射，便于追踪采集批次与来源

实用场景

• 轮询已完成采集任务：定时获取 Tripadvisor 搜索任务完成列表，减少逐个猜测任务状态的成本。
• 补偿回调失败结果：当 postback_url 回调异常时，重新找回遗漏任务 ID，数据丢失。
• 构建任务消费队列：将已完成任务 ID 投递到处理流水线，提升采集结果库效率。
• 监控任务处理时效：结合 date_posted 与任务完成列表，评估任务处理延迟并优化调度策略。
• 按标签追踪业务批次：利用 tag 对不同、地区或批次进行归档，方便后续分析与审计。