Google Hotels
Google 酒店的一条列表结果,把酒店名称、星级和地图位置,与住客评分、评价数、照片以及所选日期和币种下的最低每晚价格放在一起。把这些信号横向排开,就能比较一个目的地的酒店供给、权衡价格与口碑,并在细看单家酒店之前先把候选名单缩短。
Google Hotels API 主要特性
- 按旅客习惯的说法搜索query 可以填目的地或酒店名,例如 hotels in new york,返回 Google 酒店为它列出的酒店及展示顺序,rank 记录每家的位置。
- 按具体行程报价check_in、check_out 和 currency 决定报价对应的入住安排,每行都会带上这两个日期,以及 price.amount、price.currency 和格式化后的价格。
- 排序与每晚价格区间sort_by 可在 relevance、lowest_price、highest_rating、most_reviewed 之间切换,min_price 和 max_price 按所选币种只保留预算内的酒店。
- 每家酒店都有口碑信号stars 是酒店星级,rating 是 1 到 5 分的住客平均分,reviews_count 是评分背后的评价数量。
- 坐标与照片location 给出经纬度,方便上地图;images 列出 Google 为该酒店展示的照片地址。
- 酒店 ID 用于后续查询每行的 id 可以直接用于 Google Hotel Details API 和 Hotel Price Tracker API,url 链接到该酒店的 Google 酒店页面。
- 单次最多 140 家results_limit 可填 1 到 140;is_sponsored 标出付费推广位,便于和自然排序分开看。
Google Hotels API 参数
| 参数 | 必填 | 描述 |
|---|---|---|
query | 必填 | 目的地或酒店搜索词,例如 hotels in new york 或某家酒店的名称。 |
check_in | 可选 | 入住日期,格式为 YYYY-MM-DD,不能早于今天。需与 check_out 一起提供;两者都不传时按明天入住一晚报价。 |
check_out | 可选 | 离店日期,格式为 YYYY-MM-DD,需晚于 check_in,最长 30 晚。 |
currency | 可选 | 价格和价格区间使用的三位币种代码,例如 USD 或 EUR。 |
sort_by | 可选 | 排序方式:relevance、lowest_price、highest_rating 或 most_reviewed。 |
min_price | 可选 | 每晚最低价格,币种与 currency 一致。 |
max_price | 可选 | 每晚最高价格,币种与 currency 一致,不能低于 min_price。 |
location_code | 可选 | 搜索市场的位置代码,默认 2840(美国)。 |
language_code | 可选 | 结果的语言代码,默认 en。 |
results_limit | 可选 | 返回的酒店数量,可填 1 到 140,默认 18。 |
如何使用 Google Hotels API
提交一个目的地搜索,每行读取一家酒店。
- 向 /v1/google-hotels/search 发送 {"query": "hotels in new york", "currency": "USD", "results_limit": 18}。
- 轮询 GET /v1/tasks/{task_id},直到 status 为 succeeded。
- 从 results.items 读取酒店;has_more 为 true 时,用 results.next_cursor 请求下一页。
curl -X POST "https://api.socq.ai/v1/google-hotels/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"hotels in new york","currency":"USD","results_limit":18}'Google Hotels API 最佳使用场景
- 目的地价格对标: 在同一组日期下,把 price.amount 与 stars、rating 放在一起,看清一个城市里不同档次酒店的价位。
- 筛选候选酒店: 在价格区间内保留 rating 和 reviews_count 达标的酒店,再把它们的 id 交给详情和报价接口继续查。
- 比较出行日期: 同一个 query 换几组 check_in、check_out 重复查询,按 id 合并结果,看每家酒店在不同日期的价格变化。
- 绘制酒店分布: 用 location 的经纬度配合 stars 和价格上图,看经济型和高端酒店在一个街区里怎么分布。
Google Hotels API 使用建议
- 需要横向比较的每次查询都显式设置 currency,保证不同批次的 price.amount 单位一致。
- check_in 和 check_out 要一起传;超过 30 晚或离店早于入住,会在任务创建前被拒绝。
- 后续查询按 id 关联,不要按酒店名,同城连锁酒店的名称往往大同小异。
- results_limit 设为真正要看的酒店数即可,每返回一家酒店计 0.15 积分。
相关 API
除了 Google Hotels API,需要其他类型的 Google Hotels 公开数据时,可以使用以下 API。
- Google Hotel Details API — 按酒店 ID 获取单个酒店在 Google Hotels 上的完整资料,包括联系方式、设施、周边评分、评分分布、评论主题和各预订网站报价。
- Hotel Price Tracker API — 按酒店 ID 获取单个酒店在 Google Hotels 上的价格日历,给出未来约 6–8 周内每个入住日期的最低每晚价格。