SeerMarTech API 文档

主题

按任务 ID 获取 Tripadvisor 搜索结果 ​

接口说明 ​

该接口用于按任务 id 获取 Tripadvisor 搜索结果。

返回的数据与创建任务时提交的参数一致，主要受以下条件影响：

  • keyword
  • location_code 位置
  • 搜索参数

本接口会尽可能高精度模拟任务设置时的搜索环境，因此返回结果应接近对应时间点下的 Tripadvisor 搜索结果。你也可以通过响应中的 check_url 在浏览器无痕模式下核验结果准确性。

需要注意：

  • 系统不会引用户偏好、搜索历史等个性化因素；
  • 因此返回结果不个性化排序影响；
  • 任务创建后，结果可在 30 天重复获取；
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求方式 ​

GET https://api.seermartech.cn/v3/business_data/tripadvisor/search/task_get/$id

计费说明 ​

该接口本身按“取结果”不额外收费，账户在创建任务时扣费。 任务创建后，可在 30 天多次获取结果。

由于原始文档未提供明确单价，此处不展示人民币参考价。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

路径参数 ​

字段类型说明
idstring任务唯一标识，UUID 格式。可在任务创建后 30 天随时用于获取结果。

返回结构 ​

接口返回 JSON 编码数据，顶层 tasks 数组。

顶层字段 ​

字段类型说明
versionstring当前 API 版本
status_codeinteger通用状态码，完整错误码请参考文档中的错误码章节
status_messagestring通用状态信息
timestring执行耗时，单位秒
costfloat本次请求总成本，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorintegertasks 数组中返回错误的任务数量
tasksarray任务结果数组

tasks[] 字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码，通常范围为 10000-60000
status_messagestring任务状态信息
timestring任务执行耗时，单位秒
costfloat任务成本，单位 USD
result_countintegerresult 数组数量
patharrayURL 路径
dataobject创建任务时提交的参数副本
resultarray结果数组

result[] 字段 ​

字段类型说明
keywordstringPOST 提交时传的；如果设置了 alias，这里返回 alias
se_domainstringPOST 请求中的搜索引擎域名
location_codestringPOST 请求中的地区编码
language_codestringPOST 请求中的语言编码
check_urlstring直达 Tripadvisor 搜索结果页的链接，可用于人工核验
datetimestring抓取结果时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
item_typesarray本次结果中出现的结果类型。当前可能值：tripadvisor_search_organic
se_results_countinteger搜索结果总数
items_countinteger当前返回的结果项数量。若需更多结果，请在创建任务时增加 depth
itemsarrayTripadvisor 搜索结果列表

items[] 字段 ​

字段类型说明
typestring结果类型，当前可能值：tripadvisor_search_organic
rank_groupinteger相同 type 分组的排名
rank_absoluteinteger所有结果中的绝对排名
titlestring商家或地点名称
url_pathstring商家在 Tripadvisor 页面中的 URL 路径。可用于后续获取该商家的评论数据，例如 /v3/business_data/tripadvisor/reviews/task_post/
is_sponsoredboolean是否为赞助投放结果；为 true 表示该结果为广告位
reviews_countinteger评论总数
categorystring场所分类
price_ratestring平均价格等级
ratingobject商家评分信息

rating 对象字段 ​

字段类型说明
rating_typestring评分类型，当前可能值：Max5
valuefloat评分值
votes_countinteger反馈数量，即该商家获得的投票数
rating_maxinteger当前评分体系的最大值；Max5 对应最大值为 5

沙盒调试 ​

可使用以下沙盒地址查看本接口可返回的字段结构，字段值为演示数据，不会产生费用：

https://api.seermartech.cn/v3/business_data/tripadvisor/search/task_get/00000000-0000-0000-0000-000000000000

调用示例 ​

curl ​

bash
# 将 {id} 替换为任务 ID
id="04011058-0696-0199-0000-2196151a15cb"

curl --location --request GET "https://api.seermartech.cn/v3/business_data/tripadvisor/search/task_get/${id}" \
 --header "Authorization: Bearer smt_live_YOUR_KEY" \
 --header "Content-Type: application/json"

Python ​

python
import requests

task_id = "02231934-2604-0066-2000-570459f04879"
url = f"https://api.seermartech.cn/v3/business_data/tripadvisor/search/task_get/{task_id}"

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

response = requests.get(url, headers=headers)
print(response.status_code)
print(response.text)

TypeScript ​

typescript
const taskId = '02231934-2604-0066-2000-570459f04879';

fetch(`https://api.seermartech.cn/v3/business_data/tripadvisor/search/task_get/${taskId}`, {
 method: 'GET',
 headers: {
 'Authorization': 'Bearer smt_live_YOUR_KEY',
 'Content-Type': 'application/json'
 }
})
 .then(async (response) => {
 const data = await response.json;
 console.log(data);
 })
 .catch((error) => {
 console.error(error);
 });

结合 tasks_ready 获取已完成任务 ​

如果你是异步批量创建任务，推荐调用：

GET /v3/business_data/tripadvisor/search/tasks_ready

获取已完成任务列表，再逐个调用：

GET /v3/business_data/tripadvisor/search/task_get/$id

按任务 ID 拉取最终结果。

Python 示例：取已完成任务，再取结果 ​

python
import requests

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

# 1. 获取已完成任务
ready_url = "https://api.seermartech.cn/v3/business_data/tripadvisor/search/tasks_ready"
ready_resp = requests.get(ready_url, headers=headers)
ready_data = ready_resp.json

results = []

if ready_data.get("status_code") == 20000:
 for task in ready_data.get("tasks", []):
 for result_task in task.get("result", []):
 endpoint = result_task.get("endpoint")
 if endpoint:
 # 2. 逐个拉取任务结果
 full_url = f"https://api.seermartech.cn{endpoint}"
 resp = requests.get(full_url, headers=headers)
 results.append(resp.json)

print(results)

响应示例 ​

json
{
 "version": "0.1.20220819",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0855 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "se_type": "organic",
 "se": "tripadvisor",
 "api": "business_data",
 "function": "search",
 "keyword": "pizza",
 "location_code": 1003854,
 "depth": 10,
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 0,
 "items_count": 30,
 "items": []
 }
 ]
 }
 ]
}

状态码与异常处理 ​

建议对通用状态码和任务级状态码都做完整处理，以下场景：

  • 顶层 status_code 非成功
  • tasks_error 大于 0
  • tasks[].status_code 为错误状态
  • result 为空或不存在
  • 任务 ID 已过期（ 30 天）
  • 任务尚未完成，建议通过 /v3/business_data/tripadvisor/search/tasks_ready 轮询

错误码完整列表请参考错误码文档。

使用建议 ​

  • 若需要更多搜索结果，请在创建任务时提高 depth
  • 使用 check_url 可人工核验抓取结果是否与页面一致
  • 若要继续采集某个商家的评论，可使用返回的 url_path合 /v3/business_data/tripadvisor/reviews/task_post/
  • 建议保存任务 id，便于 30 天重复取数与问题排查

实用场景 ​

  • 监控本地商家：按城市和抓取 Tripadvisor 搜索排名，评估餐、、景点在本地搜索中的自然表现。
  • 识别竞品排名变化：定期拉取同类商家的搜索结果，跟踪竞品在目标下的排名波动，为本地 SEO 优化提供依据。
  • 筛选高评价商家线索：结合 rating、reviews_count、category 等字段，筛选高口碑且高热度的商家，用于市场研究或客户挖掘。
  • 发现广告投放对手：通过 is_sponsored 判断哪些结果为赞助位，识别竞品是否在目标上进行付费。
  • 联动评论采集分析：基于搜索结果中的 url_path 继续调用评论接口，分析用户评价、评分结构与口碑趋势。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API