SeerMarTech API 文档

主题

获取 Google店搜索任务结果 ​

接口说明 ​

通过任务 ID 获取 Google店搜索结果。

搜索接口会返回列表，并每家的价格、图片、评分等信息。你可以在创建任务时通过不同参数对结果进行筛选；本接口则用于按任务 ID 读取已完成任务的结果。

返回结果与任务创建时指定的 keyword、location 和 language 参数严格对应。本平台会尽可能高精度模拟搜索参数，使返回数据接近目标搜索条件下的结果。你也可以使用响应中的 check_url，在浏览器无痕模式下自行核验结果页面。

请求方式 ​

GET https://api.seermartech.cn/v3/business_data/google/hotel_searches/task_get/{id}

计费说明 ​

在创建任务时收费；任务结果在随后 30 天 可重复获取。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

路径参数 ​

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

Sandbox ​

你可以通过以下沙箱地址查看本端点支持的结果字段结构：

https://api.seermartech.cn/v3/business_data/google/hotel_searches/task_get/00000000-0000-0000-0000-000000000000

沙箱响应会返回该端点下所有可用字段，并填演示数据。调用 Sandbox 不计费。

返回结构 ​

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

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger接口通用状态码。完整错误码可参考 /v3/appendix/errors。建议在接时做好异常与错误处理。
status_messagestring接口通用状态信息。
timestring执行耗时，单位秒。
costfloat本次请求的总任务成本，单位 USD。读取结果通常为 0，因为创建任务时计费。
tasks_countintegertasks 数组中的任务数量。
tasks_errorintegertasks 数组中返回错误的任务数量。
tasksarray任务结果数组。

tasks[] 字段 ​

字段类型说明
idstring任务 ID，UUID 格式。
status_codeinteger任务状态码，范围通常为 10000-60000。完整错误码可参考 /v3/appendix/errors。
status_messagestring任务状态信息。
timestring任务执行耗时，单位秒。
costfloat该任务成本，单位 USD。
result_countintegerresult 数组中的数量。
patharray请求路径。
dataobject含创建任务时提交的原始参数。
resultarray结果数组。

result[] 字段 ​

字段类型说明
keywordstringPOST 数组中提交的。返回时会解码 %##；加号 + 会被解码为空格。为提高搜索准确性，系统会自动将位置名称拼接到中。
location_codeinteger创建任务时指定的位置编码。
language_codestring创建任务时指定的语言编码。
check_urlstring搜索结果直达链接，可用于人工核验结果准确性。
datetimestring结果抓取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。例如：2019-11-15 12:57:46 +00:00
items_countintegeritems 数组中的数量。
itemsarray结果项数组。当前可能值：hotel_search_item。

items[] 字段 ​

字段类型说明
typestring素类型，固定为 hotel_search_item。
hotel_identifierstring店在 Google 搜索中的唯一标识。示例：CgoI-KWyzenM_MV3EAE
titlestring店名称。
starsinteger店星级，范围通常为 1–5；某些结果中也可能为 0。
is_paidboolean是否为付费列表项。true 表示广告，false 表示自然结果。
locationobject店地理坐标。
location.latitudefloat店在地图中的纬度。示例：51.584091
location.longitudefloat店在地图中的经度。示例：-0.31365919999999997
reviewsobject店评论与评分信息。
reviews.valuefloat所有评论的平均评分。
reviews.votes_countinteger评分人数。
reviews.mentionsarray店提及信息。该字段固定为 null，用于与 /v3/business_data/google/hotel_info/live/advanced/ 保持结构容。
reviews.rating_distributionobject评分分布。该字段固定为 null，用于与 /v3/business_data/google/hotel_info/live/advanced/ 保持结构容。
reviews.other_sites_reviewsarray第三方站点评价。该字段固定为 null，用于与 /v3/business_data/google/hotel_info/live/advanced/ 保持结构容。
overview_imagesarray店展示图片。
pricesobject店价格信息。
prices.priceinteger每晚价格。
prices.price_without_discountinteger未应用折扣时的每晚原价。
prices.currencystring价格货币。默认使用 USD，除非在创建任务时另行指定。
prices.discount_textstring折扣说明文本。
prices.check_instring住时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
prices.check_outstring退房时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
prices.visitorsinteger对应价格适用的人数。
prices.itemsarray价格明细项。该字段固定为 null，用于与 /v3/business_data/google/hotel_info/live/advanced/ 保持结构容。

认证方式 ​

在请求头中使用 Bearer Token：

Authorization: Bearer smt_live_YOUR_KEY

请求示例 ​

cURL ​

bash
id="09171517-0696-0242-0000-a96bc1ad0bce"

curl --location --request GET "https://api.seermartech.cn/v3/business_data/google/hotel_searches/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/google/hotel_searches/task_get/{task_id}"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

const taskId = "02231934-2604-0066-2000-570459f04879";

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/business_data/google/hotel_searches/task_get/${taskId}`,
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then((response) => {
 // 输出结果数据
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

结合 tasks_ready 获取已完成任务 ​

通常建议调用：

GET /v3/business_data/google/hotel_searches/tasks_ready

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

GET /v3/business_data/google/hotel_searches/task_get/{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/google/hotel_searches/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_group in ready_data.get("tasks", []):
 for task_info in task_group.get("result", []) or []:
 endpoint = task_info.get("endpoint")
 if endpoint:
 # 2. 拉取每个已完成任务的结果
 full_url = f"https://api.seermartech.cn{endpoint}"
 task_resp = requests.get(full_url, headers=headers)
 results.append(task_resp.json)

print(results)

响应示例 ​

json
{
 "version": "0.1.20220720",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0739 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "se_type": "hotels",
 "se": "google",
 "api": "business_data",
 "function": "hotel_searches",
 "language_code": "en",
 "location_name": "New York,New York,United States",
 "keyword": "cheap hotel",
 "check_in": "2023-06-01",
 "check_out": "2023-06-30",
 "currency": "USD",
 "adults": 2,
 "children": [],
 "sort_by": "highest_rating",
 "tag": "example",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "keyword": "cheap hotel New York,New York,United States",
 "location_code": 2840,
 "language_code": "en",
 "check_url": "https://www.google.com/travel/search?q=cheap%20hotel",
 "datetime": "2023-06-01 00:00:00 +00:00",
 "items_count": 10,
 "items": [
 {
 "type": "hotel_search_item",
 "hotel_identifier": "ChoIpLCr95T4krHzARoNL2cvMTFiNjM2N25wZhAB",
 "title": "NobleDen Hotel",
 "stars": 3,
 "is_paid": false,
 "location": {
 "latitude": 40.719359999999995,
 "longitude": -73.99677
 },
 "reviews": {
 "value": 4.7,
 "votes_count": 458,
 "mentions": null,
 "rating_distribution": null,
 "other_sites_reviews": null
 },
 "overview_images": [],
 "prices": {
 "price": 357,
 "price_without_discount": null,
 "currency": "USD",
 "discount_text": null,
 "check_in": "2023-06-01 00:00:00 +00:00",
 "check_out": "2023-06-30 00:00:00 +00:00",
 "visitors": 3,
 "items": null
 }
 },
 {
 "type": "hotel_search_item",
 "hotel_identifier": "ChkI-JHp7LjVo4V7Gg0vZy8xMWYzYnhndDA5EAE",
 "title": "Artezen Hotel",
 "stars": 4,
 "is_paid": false,
 "location": {
 "latitude": 40.709599999999995,
 "longitude": -74.00872000000001
 },
 "reviews": {
 "value": 4.7,
 "votes_count": 400,
 "mentions": null,
 "rating_distribution": null,
 "other_sites_reviews": null
 },
 "overview_images": [],
 "prices": {
 "price": 275,
 "price_without_discount": null,
 "currency": "USD",
 "discount_text": null,
 "check_in": "2023-06-01 00:00:00 +00:00",
 "check_out": "2023-06-30 00:00:00 +00:00",
 "visitors": 3,
 "items": null
 }
 }
 ]
 }
 ]
 }
 ]
}

错误处理建议 ​

  • 检查顶层 status_code 是否为 20000
  • 再检查 tasks[].status_code 是否为成功状态
  • 若 tasks[].result 为空，说明任务可能尚未完成、任务 ID 无效，或请求存在参数/权限问题
  • 建议同时记录 status_message 便于排查

说明补 ​

  • check_url 可用于验证抓取结果是否与目标搜索页面一致。
  • keyword 返回时可能与原始不同，因为系统可能自动附加地理位置名称。
  • 部分的 prices.price、prices.currency 可能为 0 或 null，表示当前结果页未提供明确价格。
  • reviews.mentions、reviews.rating_distribution、reviews.other_sites_reviews、prices.items 在本端点中固定为 null，主要用于与端点保持字段容。

实用场景 ​

  • 回收检索任务结果：在异步创建搜索任务后，按任务 ID 拉取最终结果，完成批量采集闭环。
  • 筛选目标城市名单：基于、地区、语言返回列表，用于 SEO、目的地建设或竞品盘点。
  • 监测价格与评分分布：获取每家的价格、星级、评分和评论数，价格报与口碑分析。
  • 识别广告位与自然结果：通过 is_paid 区分付费列表和自然列表，分析竞价投放与自然格局。
  • 构建聚合数据底座：结合 hotel_identifier、坐标、评分和价格字段，沉淀可用于搜索、推荐和可视化分析的结构化数据。

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

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