Google 酒店把一个目的地的星级、住客评分、每晚价格和各预订网站报价放在同一个页面上。旅游产品、比价工具和收益管理人员需要的是这些数据的行记录:一份可比较的酒店列表、某家酒店的完整记录,以及它的价格如何随日期变化。
SocQ 于 2026-11-17 上线了 Google Hotels 平台,三个接口正好覆盖这三件事,并通过同一个字段串联:酒店 id。本文介绍每个接口返回什么、怎么请求、价格多少、适合什么场景。
快速回答: 用
POST /v1/google-hotels/search搜索目的地,保存每家酒店的id。把它作为hotel_id传给POST /v1/google-hotels/hotel-details获取设施、评价话题和各预订网站报价,或传给POST /v1/google-hotels/hotel-prices获取按入住日期的每晚最低价。轮询GET /v1/tasks/{task_id}读取结果。
新上线的 Google 酒店接口
1 SocQ 积分 = $0.005。
| 接口 | 返回内容 | 价格 |
|---|---|---|
| Google Hotels API(Google 酒店) | 某目的地的酒店,含星级、住客评分、评价数、所选日期的每晚最低价、位置、照片和酒店 id | 每家酒店 0.15 积分($0.00075) |
| Google Hotel Details API(Google 酒店详情) | 一家酒店的地址、电话、网站、设施、位置评分、评分分布、评价话题、其他网站评分,以及每个预订网站的报价 | 每次调用 2 积分($0.01) |
| Hotel Price Tracker API(酒店价格追踪) | 每个入住日期一行,给出该酒店一晚的最低价,通常覆盖六到八周的日期 | 每次调用 4 积分($0.02) |
鉴权与异步任务流程
所有 SocQ 请求都使用 API Key 鉴权,提交、任务状态和结果请求使用同一个请求头:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
每次采集都作为后台任务运行:
submit -> task_id -> queued -> running -> succeeded
\-> failed
提交响应中包含 data.task_id 和 data.status。用这个 ID 轮询任务:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
当 status 为 succeeded 时,响应会在 data.results.items 中带上第一页标准化结果。limit 默认 50,最大 500;如果 has_more 为 true,把 results.next_cursor 作为 cursor 传入即可读取下一页。任务处于 queued、running 或 failed 时,接口只返回任务元数据,不含 results。
在提交请求体中加入可选的 callback_url,任务结束后 SocQ 会发送一次带任务摘要的 POST;结果记录仍通过 GET /v1/tasks/{task_id} 读取。客户端超时不会取消任务,请用同一个任务 ID 继续查询,而不是重新提交并重复付费。402 表示积分不足;429 表示 API Key 触发了频率或积分限制。
Google Hotels API:搜索一个目的地
Google Hotels API 像旅客在 Google 上那样搜索酒店。通过 query 提供目的地或酒店搜索词。
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
}'
可选字段:
check_in和check_out(格式 YYYY-MM-DD,需同时提供,最长 30 晚)用于按具体行程报价。不传时,价格按明天入住一晚计算。currency:三位货币代码,例如USD或EUR。sort_by:relevance、lowest_price、highest_rating或most_reviewed。min_price和max_price:每晚价格范围,以所选货币计。location_code(默认 2840,美国)和language_code(默认en)。results_limit:1 到 140,默认 18。
每家酒店一行,包含 id、name、stars(1 到 5)、rating(1 到 5)、reviews_count、price(amount、currency、formatted)、价格对应的 check_in 和 check_out、is_sponsored、带经纬度的 location、images,以及在结果中的 rank。默认 18 家酒店计 2.7 积分($0.0135);上限 140 家计 21 积分($0.105)。文档:Google 酒店搜索。
Google Hotel Details API:一家酒店的全部信息
Google Hotel Details API 返回一行,包含 Google 酒店掌握的该酒店信息。把搜索结果中的 id 作为 hotel_id 传入。传入 check_in 和 check_out 可获取这几天的报价,不传时按明天入住一晚报价。
curl -X POST "https://api.socq.ai/v1/google-hotels/hotel-details" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"hotel_id": "ChoIyKbJ6puqvPf8ARoNL2cvMTFqNHR2MjczeBAB",
"currency": "USD"
}'
在搜索字段之外,详情行还会填充:
address、phone、website、check_in_time、check_out_time和amenities。location_scores:overall、things_to_do、restaurants、transit和airport_access的 1 到 5 分评分。rating_distribution:各星级评价所占比例。review_topics:例如 Location 或 Breakfast,附正面、负面和总提及数。other_reviews:该酒店在其他评价网站上的评分和评价数。offers:每个预订网站一条,含seller、price、预订url、is_official、is_sponsored和free_cancellation_until。
价格一致性检查需要的正是 offers:比较同一日期下官网报价和在线旅行社的报价。每次请求 2 积分($0.01)。hotel_id 无效时不返回结果,仍照常计费。文档:Google 酒店详情。
Hotel Price Tracker API:按入住日期的最低价
Hotel Price Tracker API 把 Google 酒店日期选择器背后的价格日历变成行记录。对一家酒店,你会得到每个入住晚的最低价,通常从你的入住日期起覆盖六到八周。
curl -X POST "https://api.socq.ai/v1/google-hotels/hotel-prices" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"hotel_id": "ChoIyKbJ6puqvPf8ARoNL2cvMTFqNHR2MjczeBAB",
"currency": "USD"
}'
check_in 决定日历的起始日期(不传时从明天开始),需与 check_out 一起提供。每行包含由酒店 ID 和日期组成的 id、hotel_id、name、check_in、check_out 和 price。可用于找出最便宜的出行日期、对比周末与工作日的定价,或为比价报告提供数据。无论返回多少个日期,每次请求都是 4 积分($0.02)。文档:酒店价格追踪。
一个简单的竞争组合分析流程
- 用
sort_by: "most_reviewed"搜索一次目的地,从结果中选出你的竞争组合。 - 为每家酒店拉取 Hotel Details,比较设施、位置评分、评价话题和各预订网站报价。
- 定期为每家酒店运行 Hotel Price Tracker,把每一行连同
collected_at一起保存。
从一次默认 18 家酒店的搜索中选出 10 家,每跑一轮是:搜索 2.7 积分、详情 20 积分、价格日历 40 积分,共 62.7 积分,约 $0.31。价格会变化,请把每一轮视为快照。Google 地图上的地点和评价等本地商户数据,见 Google Maps 采集 API。
常见问题
什么是 Google Hotels API?
一组以结构化行记录返回 Google 酒店数据的 SocQ 接口:目的地搜索结果、单家酒店的完整详情,以及每晚价格日历。它们是 SocQ 的接口,不是 Google 官方产品。
hotel_id 从哪里获取?
来自 Google 酒店搜索结果的 id 字段。同一个值可用于 Hotel Details 和 Hotel Price Tracker。
价格对应哪些日期?
如果传入 check_in 和 check_out(格式 YYYY-MM-DD,最长 30 晚),价格对应这段行程。不传时,搜索和详情按明天入住一晚报价,价格追踪的日历从明天开始。
能用其他货币显示价格吗?
能。传入三位 currency 代码,例如 EUR。每个价格对象都包含 amount、currency 和形如 USD 176 的 formatted 字符串。
hotel_id 无效也收费吗?
收费。Hotel Details 对未知 hotel_id 不返回结果,但仍收取 2 积分,所以请先用最近一次搜索的结果校验 ID。