google-hotels

🏨 Google Hotels API：以整洁的 JSON 获取酒店价格和住宿数据

使用 Google Hotels API 的高效、可靠且对开发者友好的方式。

Actor 页面： apify.com/johnvc/google-hotels-search-scraper 输入架构： apify.com/johnvc/google-hotels-search-scraper/input-schema

Google Hotels API 可搜索 Google Hotels 并返回整洁、结构化的 JSON：酒店和度假租赁房源的每晚价格和总价、优惠、星级和住宿类型、评分和评论数、设施、图片、描述、地址和 GPS 坐标，以及入住和退房时间。可按地点查询进行搜索，也可通过令牌获取单个住宿的信息。支持高级筛选、度假租赁房源、本地化（国家/地区、语言、货币）和多页分页。

新增： 通过 search_type 输入提供三种额外模式——autocomplete（目的地和酒店名称建议，附带住宿令牌）、photos（住宿的完整照片集）和 reviews（分页显示的住客评论，包含评分、文本和来源）。本仓库中每种模式都有可运行的示例脚本。

视频演示

快速开始

前提条件

• Python 3.11 或更高版本
• Apify 账号和 API 密钥（在此免费获取密钥）

1. 克隆仓库

   git clone https://github.com/johnisanerd/Apify-Google-Hotels-API.git
   cd Apify-Google-Hotels-API
   

2. 使用 UV 安装依赖项

   # Install UV if you do not have it:
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Install project dependencies:
   uv sync
   

3. 配置 API 密钥

   cp .env.example .env
   # Edit .env and add your Apify API key
   # Get your free API key at: https://apify.com?fpr=9n7kx3
   

4. 运行示例

   uv run python google-hotels-api.py            # hotel search (the classic quick start)
   uv run python google-hotels-autocomplete.py   # destination + hotel name suggestions
   uv run python google-hotels-photos.py         # full photo gallery for one hotel
   uv run python google-hotels-reviews.py        # guest reviews for one hotel
   

备选方案：直接设置 API 密钥

export APIFY_API_TOKEN="your_api_key_here"
uv run python google-hotels-api.py

为什么使用这个 Google Hotels API？

丰富的住宿数据。 每条结果都包含每晚价格和总价、优惠、评分和评论数、设施、图片、描述、GPS 坐标以及入住和退房时间，方便你直接比较各住宿。

四种数据获取模式。 按地点查询进行搜索，通过 property_token 获取单个住宿的完整详情，将不完整的查询解析为目的地和酒店建议，或获取住宿的完整照片集和住客评论。

强大的筛选功能。 可按价格范围、星级、住客评分、设施和住宿类型筛选，也可切换到度假租赁模式，并按卧室和浴室数量筛选。

可预测的按使用量付费定价。 按运行次数和处理的页数计费，无需订阅。你可以通过页数上限控制费用。

易于自动化。 只需几行 Python 代码即可调用，也可将其加载为 MCP 工具，让 Claude 和 Cursor 等助手按需为你搜索酒店。

功能

核心功能

• 按地点查询进行搜索，或通过令牌查找单个住宿
• 自动补全建议，支持不完整的查询，并提供可用于后续调用的住宿令牌
• 照片集，提供原尺寸和缩略图 URL，并按版块整理
• 住客评论，包含评分、文本、日期、来源和排序选项
• 按国家/地区、语言和货币进行本地化
• **高级筛选：**价格范围、星级、住客评分、设施、住宿类型
• 度假租赁模式，支持按卧室和浴室数量筛选
• 多页分页，可配置页数上限

数据质量

• 每晚价格和总价，包含税前价格和优惠标记
• 每处住宿的评分、评论、设施和图片
• GPS 坐标和地址，便于地图展示
• 每次查询均采用一致的 JSON 结构
• 按页记录数据集条目，确保准确计费

使用示例

基本搜索

{
  "q": "hotels in Paris",
  "check_in_date": "2026-06-29",
  "check_out_date": "2026-07-01",
  "adults": 2,
  "max_pages": 1
}

筛选搜索

{
  "q": "hotels in New York",
  "check_in_date": "2026-06-29",
  "check_out_date": "2026-07-01",
  "adults": 2,
  "min_price": "100",
  "max_price": "300",
  "hotel_class": "4,5",
  "currency": "USD",
  "max_pages": 1
}

度假租赁房源

{
  "q": "vacation rentals in Miami",
  "check_in_date": "2026-06-29",
  "check_out_date": "2026-07-03",
  "adults": 4,
  "vacation_rentals": true,
  "bedrooms": 2,
  "bathrooms": 2,
  "max_pages": 1
}

自动补全建议（参见 google-hotels-autocomplete.py）

{
  "search_type": "autocomplete",
  "q": "hotels in par",
  "gl": "us",
  "hl": "en"
}

每条建议返回一个数据集条目。针对特定酒店的建议包含一个 property_token，可将其用于获取照片、评论或住宿详情。

酒店照片（参见 google-hotels-photos.py）

{
  "search_type": "photos",
  "property_token": "ChUIksaK9_ij5_kYGgkvbS8wNjJ3YzIQAQ",
  "max_pages": 1
}

每张照片返回一个数据集条目（每家酒店通常有 100-200 张），包含 photo_url、thumbnail_url、尺寸、相册分区和来源。

住客评价（参见 google-hotels-reviews.py）

{
  "search_type": "reviews",
  "property_token": "ChUIksaK9_ij5_kYGgkvbS8wNjJ3YzIQAQ",
  "reviews_sort_by": "2",
  "max_pages": 2
}

每条评价返回一个数据集条目，包含评分、文本、日期、来源平台、评价者详情，以及酒店在有回复时提供的回复。使用 reviews_sort_by 排序："1" 最有帮助，"2" 最新，"3" 评分最高，"4" 评分最低。

输入参数

必须提供 q（搜索查询）或 property_token。

参数	类型	必填	默认值	描述
search_type	string	否	search	search、autocomplete、photos 或 reviews。
q	string	是*	-	搜索查询，例如 hotels in Paris。search（除非已设置 property_token）和 autocomplete 必填。
property_token	string	是*	-	单个酒店的令牌（来自之前的结果或自动补全）。photos 和 reviews 必填；在 search 模式下返回酒店详细信息。
gl	string	否	us	国家代码（ISO 3166-1 alpha-2）。
hl	string	否	en	语言代码（ISO 639-1）。
currency	string	否	（按国家）	货币代码（ISO 4217），例如 USD、EUR。
check_in_date	string	否	-	入住日期，格式为 YYYY-MM-DD（建议与查询搭配使用）。
check_out_date	string	否	-	退房日期，格式为 YYYY-MM-DD。
adults	integer	否	2	成人住客人数。
children	integer	否	0	儿童住客人数（若 > 0，则必须提供 children_ages）。
min_price / max_price	string	否	0.00	按所选货币筛选价格范围。
stars	string	否	-	以逗号分隔的星级，例如 4,5。
hotel_class	string	否	-	以逗号分隔的等级 2-5。
guest_rating	string	否	0.0	最低住客评分（0.0 至 5.0）。
vacation_rentals	boolean	否	false	包含度假租赁房源（启用 bedrooms/bathrooms）。
reviews_sort_by	string	否	1	评价排序：1 最有帮助，2 最新，3 评分最高，4 评分最低。
reviews_category_token	string	否	-	按酒店评价细分中的类别令牌筛选评价。
max_pages	integer	否	1	要获取的最大页数（0 = 不限）。适用于搜索、照片和评价。
output_file	string	否	-	用于保存结果的可选文件名。

其他筛选条件（amenities、property_type、rental_type）接受 Google 的整数 ID；完整参考请参见 Actor 页面。

输出格式

hotels in Paris 的真实结果（每页一个条目；为便于阅读，properties 数组已缩减为仅包含一个条目）。

{
  "search_parameters": {
    "q": "hotels in Paris",
    "gl": "us",
    "hl": "en",
    "currency": "USD",
    "check_in_date": "2026-06-29",
    "check_out_date": "2026-07-01",
    "adults": 2,
    "max_pages": 1
  },
  "search_metadata": {
    "total_results": 15000,
    "properties_count": 20,
    "ads_count": 0,
    "pages_processed": 1,
    "max_pages_set": 1,
    "pagination_limit_reached": true
  },
  "page_number": 1,
  "properties": [
    {
      "type": "hotel",
      "name": "The Originals Boutique, Hôtel Maison Montmartre, Paris",
      "description": "Hip hotel featuring a sophisticated restaurant & a cool rooftop eatery/bar with a terrace.",
      "link": "https://www.hotelmaisonmontmartre.com/",
      "property_token": "ChoI_uTZsvz1i6-bARoNL2cvMTFmZHB6eDEwMxAB",
      "gps_coordinates": { "latitude": 48.900537, "longitude": 2.336269 },
      "check_in_time": "3:00 PM",
      "check_out_time": "12:00 PM",
      "rate_per_night": { "lowest": "$144", "extracted_lowest": 144, "before_taxes_fees": "$120" },
      "total_rate": { "lowest": "$287", "extracted_lowest": 287 }
    }
  ],
  "ads": [],
  "filters": [],
  "refine_by": []
}

---

n8n 集成

可通过 n8n 社区节点使用：n8n-nodes-google-hotels-api。在 n8n 中：依次打开 Settings、Community Nodes，安装 n8n-nodes-google-hotels-api，然后在任意工作流中使用（也可作为 AI Agent 工具使用）。版本 0.2.0 新增了 Get Autocomplete Suggestions、Get Photos 和 Get Reviews 操作。

用作 MCP 工具

你可以将 Google Hotels API 加载为 MCP 工具，让助手为你调用。MCP 服务 URL 仅预加载此 Actor：

https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper

在浏览器中按提示使用 OAuth 验证，或使用你的 Apify API 令牌（与 Python 示例中使用的 APIFY_API_TOKEN 相同）。可在 https://console.apify.com/settings/integrations 获取令牌，并在 https://apify.com?fpr=9n7kx3 注册免费的 Apify 账户。

在 Claude Cowork 桌面应用中安装

Cowork 是桌面应用的自动化模式。若要将 Google Hotels API 作为工具提供给它，请添加 Apify MCP 服务作为连接器。

1. 打开 Claude 桌面应用，前往 Settings → Connectors（或前往 Settings → Developer → Edit Config，直接编辑 claude_desktop_config.json）。
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
2. 添加 Apify MCP 服务，并仅预加载此 Actor：

{
  "mcpServers": {
    "apify": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper"
      ]
    }
  }
}

3. 重启应用。Cowork 首次调用工具时，请在浏览器中完成 OAuth 提示，或在连接器设置中添加 Apify API 令牌以跳过 OAuth。
4. 在 Cowork 聊天中确认工具可用，并让它运行 Google Hotels API。

下载桌面应用并开始免费试用：https://claude.ai/referral/uIlpa7nPLg 更多帮助：https://docs.apify.com/platform/integrations/claude-desktop

在 Claude Code 中安装

Claude Code 是命令行工具。使用一条命令添加 Actor 的 MCP 服务：

claude mcp add --transport http apify \
  "https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper"

若要使用令牌而非浏览器 OAuth：

claude mcp add --transport http apify \
  "https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper" \
  --header "Authorization: Bearer YOUR_APIFY_TOKEN"

然后使用 claude mcp list 验证，或在会话中运行 /mcp。让 Claude Code 调用 Google Hotels API。

免费试用 Claude Code：https://claude.ai/referral/uIlpa7nPLg Claude Code MCP 文档：https://code.claude.com/docs/en/mcp

在 Claude（网站）中安装

在 claude.ai 上，你可以将 Apify 添加为连接器，然后仅启用此 Actor 的工具。

1. 前往 Settings → Connectors → Browse connectors，搜索 Apify MCP server。安装它（如果出现提示，请启用或更新）。
2. 连接时，使用 Apify API 令牌进行身份验证，并启用工具 johnvc/google-hotels-search-scraper。
3. 在任意聊天中，打开 + → Connectors 并启用 Apify。
4. 或者，选择 Add custom connector 并粘贴完整的 MCP URL https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper，并在出现提示时使用 OAuth。
5. 让 Claude 运行 Google Hotels API。

在网页上打开 Claude：https://claude.ai/referral/uIlpa7nPLg

在 Cursor 中安装

Cursor 从项目文件 .cursor/mcp.json 中读取 MCP 服务。

1. 在项目中创建 .cursor/mcp.json：

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper"
    }
  }
}

2. 如果你更倾向于使用令牌身份验证，而非浏览器 OAuth，请添加一个标头：

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper",
      "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" }
    }
  }
}

3. 打开 Cursor → Settings → MCP，确认 apify 服务已连接（绿点）。
4. 在 Composer 或 Chat 中，让 Cursor 调用 Google Hotels API。

刚开始使用 Cursor？在此获取：https://cursor.com/referral?code=XQP4VBLI3NNX

在 ChatGPT 中安装

ChatGPT 通过开发者模式连接 Apify MCP 服务（适用于 ChatGPT Pro、Plus、Business、Enterprise 和 Education 套餐）。

1. 点击个人资料图标，然后前往 Settings > Apps。如果看不到 Create app 按钮，请打开 Advanced settings 并启用 Developer mode。
2. 点击 Create app 并填写表单：
   • Name： Apify
   • MCP Server URL： https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper
   • Authentication： OAuth
3. 点击 Create，并通过 Apify 授权连接。
4. 若要在对话中使用该应用，请点击聊天中的 +，选择 Developer mode，然后选择 Apify。

更多帮助：https://docs.apify.com/platform/integrations/mcp

---

用心打造

使用 Google Hotels API，通过可靠、结构化的结果为价格监控、旅行应用和市场研究提供支持。

🤖 向 AI 助手咨询此 Actor

在你选择的 AI 中打开一条可直接发送的提示词，了解 Google Hotels API：

• 💬 ChatGPT
• 🧠 Claude
• 🔍 Perplexity
• 🅒 Copilot

最后更新：2026.10.27