SeerMarTech API 文档

主题

Google店搜索实时接口 ​

接口说明 ​

该接口用于实时获取 Google Hotels 中的搜索结果，返回指定地区与语言环境下的列表、评分、价格、坐标等信息。

接口返回受以下条件影响：

  • 搜索地区
  • 搜索语言 -住/离店日期
  • 住客人数 -店星级、评分、价格区间、设施条件等筛选项

请求地址 ​

POST https://api.seermartech.cn/v3/business_data/google/hotel_searches/live

计费说明 ​

该接口按请求计费。

参考价约 ¥0.0640 / 次。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式 ​

  • 请求方法：POST
  • 编码格式：UTF-8
  • 请求体：JSON 数组 [{ ... }]
  • 频率限制：最高 2000 次 API 调用/分钟

请求参数 ​

以下为任务设置字段说明。

字段名类型说明
keywordstring可选。用于搜索列表的。若不传，则返回指定位置下的列表。最长 700 个字符。 %## 会被解码，+ 会被解码为空格；如需在中保留 %，请写为 %25。为提升搜索准确性，系统会自动将位置名称追加到后。
location_namestring当未提供 location_code 或 location_coordinate 时填。搜索引擎位置完整名称，例如：London,England,United Kingdom。使用该字段时无需再传 location_code 或 location_coordinate。可通过 /v3/business_data/google/locations 获取可用位置。系统会自动将 location_name 追加到后。
location_codeinteger当未提供 location_name 或 location_coordinate 时填。搜索引擎位置编码，例如：2840。使用该字段时无需再传 location_name 或 location_coordinate。可通过 /v3/business_data/google/locations 获取可用位置。
location_coordinatestring当未提供 location_name 或 location_code 时填。位置 GPS 坐标，格式为 "latitude,longitude"，经纬度最多 7 位小数，例如：53.476225,-2.243572。若使用坐标，搜索会在最近的聚地进行。
search_this_areaboolean可选。是否显示当前展示区域的。可选值：true、false，默认 true。若设为 false，将 search_this_area 模式；此时搜索时不会自动将 location_name 附加到 keyword。
language_namestring当未提供 language_code 时填。搜索语言完整名称，例如：English。使用该字段时无需再传 language_code。可通过 /v3/business_data/google/languages 获取可用语言。
language_codestring当未提供 language_name 时填。搜索语言代码，例如：en。使用该字段时无需再传 language_name。可通过 /v3/business_data/google/languages 获取可用语言代码。
depthinteger可选。解析深度，即返回的结果数量。默认 18，最大 140。注意：按每 18 条自然结果计费，不受响应中付费条目数量影响。 如果设置大于 18 且返回 18 条，可能产生额外费用；若设置值高于返回数量，差额会自动退回余额。
check_instring可选。日期，格式：yyyy-mm-dd，例如：2019-01-15。默认使用明天日期。该值不能早于当天。
check_outstring可选。离店日期，格式：yyyy-mm-dd，例如：2019-01-15。默认使用后天日期。该值大于 check_in，且与 check_in 的间隔不能 30 天。
currencystring可选。币种，例如：USD。
adultsinteger可选。成人数量，默认 2。成人与儿童总人数最多为 6。例如：1。
childrenarray可选。儿童年龄数组；不传则表示不含儿童。儿童年龄范围 0 到 17。成人与儿童总人数最多为 6。例如：[14] 表示 1 名 14 岁儿童；[13,8] 表示 1 名 13 岁儿童和 1 名 8 岁儿童。
starsarray可选。星级筛选。例如：[5] 表示返回 5 星。
min_ratingfloat可选。最低住客评分阈值，例如：2.5。
sort_bystring可选。结果排序方式。可选值：relevance（最）、lowest_price（最低价格）、highest_rating（最高评分）、most_reviewed（评论最多）。默认：relevance。
min_priceinteger可选。每晚最低价格，币种由 currency 决定，例如：100。
max_priceinteger可选。每晚最高价格，币种由 currency 决定，例如：600。
free_cancellationboolean可选。是否返回支持取消的。设为 true 时启用。默认 false。
is_vacation_rentalsboolean可选。是否搜索度假租赁房源而非。设为 true 时启用。默认 false。
amenitiesarray可选。设施筛选。可传多个设施值。
tagstring可选。自定义任务标识，最长 255 字符。可用于将请求与返回结果进行对应；响应中的 data 对象会返回该值。

amenities 可选值 ​

  • air_conditioning
  • all_inclusive_available
  • bar
  • free_breakfast
  • fitness_center
  • kid_friendly
  • free_parking
  • pets_allowed
  • pool
  • restaurant
  • room_service
  • spa
  • free_wifi
  • parking
  • indoor_pool
  • outdoor_pool
  • wheelchair_accessible
  • beach_access

响应结构 ​

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

顶层字段 ​

字段名类型说明
versionstringAPI 当前版本。
status_codeinteger通用状态码。错误码列表参考 /v3/appendix/errors。建议在接时做好异常与错误处理。
status_messagestring通用状态说明。
timestring执行耗时，单位秒。
costfloat本次请求总费用，单位 USD。
tasks_countintegertasks 数组中的任务数。
tasks_errorinteger返回错误的任务数量。
tasksarray任务结果数组。

tasks[] 字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger任务状态码，范围通常为 10000-60000。
status_messagestring任务状态说明。
timestring任务执行耗时。
costfloat该任务费用，单位 USD。
result_countintegerresult 数组中的数量。
patharrayURL 路径。
dataobject回显请求中提交的参数。
resultarray结果数组。

result[] 字段 ​

字段名类型说明
keywordstring请求中的。返回时 %## 已解码，+ 会解码为空格。
location_codeinteger请求中的位置编码。
language_codestring请求中的语言代码。
check_urlstring搜索结果直达链接，可用于核验结果。
datetimestring结果抓取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
items_countintegeritems 数组中的数量。
itemsarray搜索结果项数组，当前可能值为 hotel_search_item。

items[] = hotel_search_item ​

字段名类型说明
typestring固定为 hotel_search_item。
hotel_identifierstring店在 Google 搜索中的唯一标识，例如：CgoI-KWyzenM_MV3EAE。
titlestring店名称。
starsinteger店星级，范围 1-5；部分结果可能为 0。
is_paidboolean是否为付费广告位。true 为广告，false 为自然结果。
locationobject店地理坐标。
location.latitudefloat店纬度。
location.longitudefloat店经度。
reviewsobject评分与评论信息。
reviews.valuefloat平均评分。
reviews.votes_countinteger评分人数。
reviews.mentionsarray店提及信息。该字段始终为 null，用于与 /v3/business_data/google/hotel_info/live/advanced/ 接口保持容。
reviews.rating_distributionobject各评分分布。该字段始终为 null，用于容扩展接口。
reviews.other_sites_reviewsarray第三方站点评价。该字段始终为 null，用于容扩展接口。
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/ 接口保持容。

请求示例 ​

curl ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/business_data/google/hotel_searches/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "New York,New York,United States",
 "language_name": "English",
 "keyword": "cheap hotel",
 "check_in": "2023-06-01",
 "check_out": "2023-06-30",
 "currency": "USD",
 "adults": 2,
 "children": [13, 8],
 "sort_by": "highest_rating",
 "tag": "example"
 }
]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/business_data/google/hotel_searches/live"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

payload = [
 {
 # 示例 1：基础查询
 "location_code": 1023191,
 "language_code": "en",
 "keyword": "cheap hotel"
 },
 {
 # 示例 2：带更多筛选参数的查询
 "location_name": "New York,New York,United States",
 "language_name": "English",
 "keyword": "cheap hotel",
 "check_in": "2023-06-01",
 "check_out": "2023-06-30",
 "currency": "USD",
 "adults": 2,
 "children": [13, 8],
 "sort_by": "highest_rating",
 "tag": "example"
 }
]

response = requests.post(url, headers=headers, json=payload)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

const postData = [
 {
 location_name: "New York,New York,United States",
 language_name: "English",
 keyword: "cheap hotel",
 check_in: "2023-06-01",
 check_out: "2023-06-30",
 currency: "USD",
 adults: 2,
 children: [13, 8],
 sort_by: "highest_rating",
 tag: "example"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/business_data/google/hotel_searches/live",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postData
})
 .then((response) => {
 // 输出接口返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error.response?.data || error.message);
 });

响应示例 ​

json
{
 "version": "0.1.20220720",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "3.0818 sec.",
 "cost": 0.004,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "business_data",
 "function": "hotel_searches",
 "se": "google",
 "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": [13, 8],
 "sort_by": "highest_rating",
 "tag": "example",
 "se_type": "hotels",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "keyword": "cheap hotel",
 "location_code": 1023191,
 "language_code": "en",
 "datetime": "2023-06-01 00:00:00 +00:00",
 "items_count": 3,
 "items": [
 {
 "type": "hotel_search_item",
 "hotel_identifier": "ChoI7vrv6_WwzZzDARoNL2cvMTFyOXR4M2tuMhAB",
 "title": "Wingate by Wyndham Bronx/Haven Park",
 "stars": 3,
 "is_paid": false,
 "location": {
 "latitude": 40.8129998,
 "longitude": -73.92864449999999
 },
 "reviews": {
 "value": 4.8,
 "votes_count": 377,
 "mentions": null,
 "rating_distribution": null,
 "other_sites_reviews": null
 },
 "overview_images": [],
 "prices": {
 "price": 0,
 "price_without_discount": null,
 "currency": null,
 "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": "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 表示整次请求状态
  • tasks[].status_code 表示单个任务状态
  • 建议同时检查：
  • HTTP 状态码
  • 顶层 status_code
  • 单任务 tasks[].status_code

完整错误码说明可参考 /v3/appendix/errors。

常见处理建议：

  • 20000：请求成功
  • 非成功状态：记录 status_message 并结合请求参数排查
  • 若涉及批量任务，需逐个检查 tasks 中每个任务的状态与结果

使用说明与注意事项 ​

  1. 位置参数三选一
  • location_name
  • location_code
  • location_coordinate

三至少传一个。

  1. 语言参数二选一
  • language_name
  • language_code

二至少传一个。

  1. 自动拼接位置 默认，为了提高搜索准确率，系统会自动把位置名追加到后。

  2. 区域搜索的影响 若 search_this_area=false，则不会将 location_name 自动追加到 keyword。

  3. 儿童参数传法children 不是儿童数量，而是儿童年龄数组。

  4. 价格字段可能为空 某些结果中 prices.currency、prices.price_without_discount 等字段可能返回 null。

  5. 部分容字段固定为 null 括：

  • reviews.mentions
  • reviews.rating_distribution
  • reviews.other_sites_reviews
  • prices.items

这些字段主要用于与接口做结构容。

实用场景 ​

  • 筛选目的地高性价比：按价格区间、星级、评分、取消等条件批量获取候选，支持、OTA 比价或商推荐策略。
  • 监控本地搜索格局：按城市、商圈或坐标抓取列表，分析自然结果与付费结果分布，评估本地市场竞争。
  • 构建榜单页：按“评分最高”“评论最多”“价格最低”等方式排序，快速生成城市推荐、亲子榜单、商务出行专题页。
  • 分析用户搜索偏好条件：结合设施字段如 free_wifi、pool、spa、pets_allowed 等，研究不同人群的住宿偏好并优化落地页。
  • 联动接口做深度分析：通过本接口获取列表与 hotel_identifier，再进一步查询页数据，构建完整的数据分析链路。

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

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