{
  "markdown": "# 🏨 Google Hotels API: Hotel Prices and Property Data in Clean JSON\n\n> The most efficient, reliable, and developer-friendly way to use the Google Hotels API.\n\n**Actor page:** [apify.com/johnvc/google-hotels-search-scraper](https://apify.com/johnvc/google-hotels-search-scraper?fpr=9n7kx3)\n**Input schema:** [apify.com/johnvc/google-hotels-search-scraper/input-schema](https://apify.com/johnvc/google-hotels-search-scraper/input-schema?fpr=9n7kx3)\n\nThe Google Hotels API searches Google Hotels and returns clean, structured JSON: hotel and vacation-rental listings with nightly and total prices, deals, star class and property type, ratings and review counts, amenities, images, descriptions, addresses and GPS coordinates, and check-in/check-out times. Search by location query or fetch one property by token. Supports advanced filters, vacation rentals, localization (country, language, currency), and multi-page pagination.\n\n**New:** three additional modes via the `search_type` input - **autocomplete** (destination and hotel name suggestions with property tokens), **photos** (a property's full photo gallery), and **reviews** (paginated guest reviews with ratings, text, and sources). Each has its own runnable example script in this repo.\n\n## Video Walkthrough\n\n[![Watch the walkthrough](https://img.youtube.com/vi/jREWahDGhJM/maxresdefault.jpg)](https://www.youtube.com/watch?v=jREWahDGhJM)\n\n## Quick Start\n\n### Prerequisites\n- Python 3.11 or higher\n- An Apify account and API key ([get a free key here](https://apify.com?fpr=9n7kx3))\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/johnisanerd/Apify-Google-Hotels-API.git\n   cd Apify-Google-Hotels-API\n   ```\n\n2. **Install dependencies with UV**\n   ```bash\n   # Install UV if you do not have it:\n   curl -LsSf https://astral.sh/uv/install.sh | sh\n\n   # Install project dependencies:\n   uv sync\n   ```\n\n3. **Configure your API key**\n   ```bash\n   cp .env.example .env\n   # Edit .env and add your Apify API key\n   # Get your free API key at: https://apify.com?fpr=9n7kx3\n   ```\n\n4. **Run the examples**\n   ```bash\n   uv run python google-hotels-api.py            # hotel search (the classic quick start)\n   uv run python google-hotels-autocomplete.py   # destination + hotel name suggestions\n   uv run python google-hotels-photos.py         # full photo gallery for one hotel\n   uv run python google-hotels-reviews.py        # guest reviews for one hotel\n   ```\n\n### Alternative: set the API key directly\n```bash\nexport APIFY_API_TOKEN=\"your_api_key_here\"\nuv run python google-hotels-api.py\n```\n\n## Why Use This Google Hotels API?\n\n**Rich property data.** Each result includes nightly and total prices, deals, ratings and review counts, amenities, images, descriptions, GPS coordinates, and check-in/check-out times, so you can compare properties directly.\n\n**Four retrieval modes.** Search by a location query, fetch full details for one property by `property_token`, resolve partial queries into destinations and hotels with autocomplete, or pull a property's complete photo gallery and guest reviews.\n\n**Powerful filters.** Constrain by price range, star class, guest rating, amenities, and property type, and switch to vacation rentals with bedroom and bathroom filters.\n\n**Predictable, pay-per-use pricing.** Per run plus per page processed, with no subscription. You control cost with the page limit.\n\n**Easy to automate.** Call it from Python in a few lines, or load it as an MCP tool so assistants like Claude and Cursor can search hotels for you on demand.\n\n## Features\n\n### Core Capabilities\n- **Location-query search** or single-property lookup by token\n- **Autocomplete suggestions** for partial queries, with property tokens for chaining\n- **Photo galleries** with full-size and thumbnail URLs, organized by section\n- **Guest reviews** with ratings, text, dates, sources, and sort options\n- **Localization** by country, language, and currency\n- **Advanced filters**: price range, star class, guest rating, amenities, property type\n- **Vacation-rental mode** with bedroom and bathroom filters\n- **Multi-page pagination** with a configurable page cap\n\n### Data Quality\n- **Nightly and total rates** with pre-tax figures and deal flags\n- **Ratings, reviews, amenities, and images** per property\n- **GPS coordinates and addresses** for mapping\n- **Consistent JSON** shape across every query\n- **Per-page dataset items** for accurate billing\n\n## Usage Examples\n\n### Basic search\n```json\n{\n  \"q\": \"hotels in Paris\",\n  \"check_in_date\": \"2026-06-29\",\n  \"check_out_date\": \"2026-07-01\",\n  \"adults\": 2,\n  \"max_pages\": 1\n}\n```\n\n### Filtered search\n```json\n{\n  \"q\": \"hotels in New York\",\n  \"check_in_date\": \"2026-06-29\",\n  \"check_out_date\": \"2026-07-01\",\n  \"adults\": 2,\n  \"min_price\": \"100\",\n  \"max_price\": \"300\",\n  \"hotel_class\": \"4,5\",\n  \"currency\": \"USD\",\n  \"max_pages\": 1\n}\n```\n\n### Vacation rentals\n```json\n{\n  \"q\": \"vacation rentals in Miami\",\n  \"check_in_date\": \"2026-06-29\",\n  \"check_out_date\": \"2026-07-03\",\n  \"adults\": 4,\n  \"vacation_rentals\": true,\n  \"bedrooms\": 2,\n  \"bathrooms\": 2,\n  \"max_pages\": 1\n}\n```\n\n### Autocomplete suggestions (see `google-hotels-autocomplete.py`)\n```json\n{\n  \"search_type\": \"autocomplete\",\n  \"q\": \"hotels in par\",\n  \"gl\": \"us\",\n  \"hl\": \"en\"\n}\n```\nReturns one dataset item per suggestion. Suggestions for specific hotels include a `property_token` you can chain into photos, reviews, or property details.\n\n### Property photos (see `google-hotels-photos.py`)\n```json\n{\n  \"search_type\": \"photos\",\n  \"property_token\": \"ChUIksaK9_ij5_kYGgkvbS8wNjJ3YzIQAQ\",\n  \"max_pages\": 1\n}\n```\nReturns one dataset item per photo (typically 100-200 per property) with `photo_url`, `thumbnail_url`, dimensions, gallery section, and source.\n\n### Guest reviews (see `google-hotels-reviews.py`)\n```json\n{\n  \"search_type\": \"reviews\",\n  \"property_token\": \"ChUIksaK9_ij5_kYGgkvbS8wNjJ3YzIQAQ\",\n  \"reviews_sort_by\": \"2\",\n  \"max_pages\": 2\n}\n```\nReturns one dataset item per review with rating, text, date, source platform, reviewer details, and the hotel's response when one exists. Sort with `reviews_sort_by`: `\"1\"` most helpful, `\"2\"` most recent, `\"3\"` highest score, `\"4\"` lowest score.\n\n## Input Parameters\n\nEither `q` (search query) or `property_token` is required.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `search_type` | `string` | No | `search` | `search`, `autocomplete`, `photos`, or `reviews`. |\n| `q` | `string` | Yes* | - | Search query, e.g. `hotels in Paris`. Required for `search` (unless `property_token` is set) and `autocomplete`. |\n| `property_token` | `string` | Yes* | - | Token for a single property (from a prior result or autocomplete). Required for `photos` and `reviews`; returns detailed property info in `search` mode. |\n| `gl` | `string` | No | `us` | Country code (ISO 3166-1 alpha-2). |\n| `hl` | `string` | No | `en` | Language code (ISO 639-1). |\n| `currency` | `string` | No | (by country) | Currency code (ISO 4217), e.g. `USD`, `EUR`. |\n| `check_in_date` | `string` | No | - | Check-in date, `YYYY-MM-DD` (recommended with a query). |\n| `check_out_date` | `string` | No | - | Check-out date, `YYYY-MM-DD`. |\n| `adults` | `integer` | No | `2` | Number of adult guests. |\n| `children` | `integer` | No | `0` | Number of child guests (`children_ages` required if > 0). |\n| `min_price` / `max_price` | `string` | No | `0.00` | Price range filter in the chosen currency. |\n| `stars` | `string` | No | - | Comma-separated star ratings, e.g. `4,5`. |\n| `hotel_class` | `string` | No | - | Comma-separated class levels `2`-`5`. |\n| `guest_rating` | `string` | No | `0.0` | Minimum guest rating (0.0 to 5.0). |\n| `vacation_rentals` | `boolean` | No | `false` | Include vacation rentals (enables `bedrooms`/`bathrooms`). |\n| `reviews_sort_by` | `string` | No | `1` | Reviews order: `1` most helpful, `2` most recent, `3` highest score, `4` lowest score. |\n| `reviews_category_token` | `string` | No | - | Filter reviews by a category token from a property's reviews breakdown. |\n| `max_pages` | `integer` | No | `1` | Maximum pages to fetch (`0` = no limit). Applies to search, photos, and reviews. |\n| `output_file` | `string` | No | - | Optional filename to save results. |\n\nAdditional filters (`amenities`, `property_type`, `rental_type`) accept Google's integer IDs; see the Actor page for the full reference.\n\n## Output Format\n\nA real result for `hotels in Paris` (one item per page; the `properties` array is trimmed to one entry for readability).\n\n```json\n{\n  \"search_parameters\": {\n    \"q\": \"hotels in Paris\",\n    \"gl\": \"us\",\n    \"hl\": \"en\",\n    \"currency\": \"USD\",\n    \"check_in_date\": \"2026-06-29\",\n    \"check_out_date\": \"2026-07-01\",\n    \"adults\": 2,\n    \"max_pages\": 1\n  },\n  \"search_metadata\": {\n    \"total_results\": 15000,\n    \"properties_count\": 20,\n    \"ads_count\": 0,\n    \"pages_processed\": 1,\n    \"max_pages_set\": 1,\n    \"pagination_limit_reached\": true\n  },\n  \"page_number\": 1,\n  \"properties\": [\n    {\n      \"type\": \"hotel\",\n      \"name\": \"The Originals Boutique, Hôtel Maison Montmartre, Paris\",\n      \"description\": \"Hip hotel featuring a sophisticated restaurant & a cool rooftop eatery/bar with a terrace.\",\n      \"link\": \"https://www.hotelmaisonmontmartre.com/\",\n      \"property_token\": \"ChoI_uTZsvz1i6-bARoNL2cvMTFmZHB6eDEwMxAB\",\n      \"gps_coordinates\": { \"latitude\": 48.900537, \"longitude\": 2.336269 },\n      \"check_in_time\": \"3:00 PM\",\n      \"check_out_time\": \"12:00 PM\",\n      \"rate_per_night\": { \"lowest\": \"$144\", \"extracted_lowest\": 144, \"before_taxes_fees\": \"$120\" },\n      \"total_rate\": { \"lowest\": \"$287\", \"extracted_lowest\": 287 }\n    }\n  ],\n  \"ads\": [],\n  \"filters\": [],\n  \"refine_by\": []\n}\n```\n\n---\n\n## n8n integration\n\nAvailable as an n8n community node, **[n8n-nodes-google-hotels-api](https://www.npmjs.com/package/n8n-nodes-google-hotels-api)**. In n8n: Settings, Community Nodes, install `n8n-nodes-google-hotels-api`, then use it in any workflow (it also works as an AI Agent tool). Version 0.2.0 adds Get Autocomplete Suggestions, Get Photos, and Get Reviews operations.\n\n## Use as an MCP tool\n\nYou can load the Google Hotels API as an MCP tool so assistants call it for you. The MCP server URL preloads just this one Actor:\n\n```\nhttps://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper\n```\n\nAuthenticate with OAuth in the browser when offered, or with your Apify API token (the same `APIFY_API_TOKEN` used by the Python example). Get a token at https://console.apify.com/settings/integrations and a free Apify account at https://apify.com?fpr=9n7kx3 .\n\n## Install in Claude Cowork Desktop\n\n![Install in Claude Cowork Desktop](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_claude_desktop.png)\n\nCowork is the desktop app's automation mode. To give it the Google Hotels API as a tool, add the Apify MCP server as a connector.\n\n1. Open the Claude desktop app and go to **Settings → Connectors** (or **Settings → Developer → Edit Config** to edit `claude_desktop_config.json` directly).\n   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n2. Add the Apify MCP server, preloaded with only this Actor:\n\n```json\n{\n  \"mcpServers\": {\n    \"apify\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper\"\n      ]\n    }\n  }\n}\n```\n\n3. Restart the app. When Cowork first calls the tool, complete the OAuth prompt in your browser, or add your Apify API token in the connector settings to skip OAuth.\n4. In a Cowork chat, confirm the tool is available and ask it to run the Google Hotels API.\n\nDownload the desktop app and start a free trial: https://claude.ai/referral/uIlpa7nPLg\nMore help: https://docs.apify.com/platform/integrations/claude-desktop\n\n## Install in Claude Code\n\n![Install in Claude Code](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_claude_code.png)\n\nClaude Code is the command-line tool. Add the Actor's MCP server with one command:\n\n```bash\nclaude mcp add --transport http apify \\\n  \"https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper\"\n```\n\nTo use a token instead of browser OAuth:\n\n```bash\nclaude mcp add --transport http apify \\\n  \"https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper\" \\\n  --header \"Authorization: Bearer YOUR_APIFY_TOKEN\"\n```\n\nThen verify with `claude mcp list`, or run `/mcp` inside a session. Ask Claude Code to call the Google Hotels API.\n\nTry Claude Code free: https://claude.ai/referral/uIlpa7nPLg\nClaude Code MCP docs: https://code.claude.com/docs/en/mcp\n\n## Install in Claude (website)\n\n![Install in Claude (website)](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_claude_ai.png)\n\nOn claude.ai you add Apify as a connector, then enable just this Actor's tool.\n\n1. Go to **Settings → Connectors → Browse connectors** and search for **Apify MCP server**. Install it (enable or update if prompted).\n2. When connecting, authenticate with your Apify API token, and enable the tool `johnvc/google-hotels-search-scraper`.\n3. In any chat, open **+ → Connectors** and turn on **Apify**.\n4. Alternatively, choose **Add custom connector** and paste the full MCP URL `https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper`, using OAuth when prompted.\n5. Ask Claude to run the Google Hotels API.\n\nOpen Claude on the web: https://claude.ai/referral/uIlpa7nPLg\n\n## Install in Cursor\n\n![Install in Cursor](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_cursor.png)\n\nCursor reads MCP servers from a project file at `.cursor/mcp.json`.\n\n1. In your project, create `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"apify\": {\n      \"url\": \"https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper\"\n    }\n  }\n}\n```\n\n2. If you prefer token auth over browser OAuth, add a header:\n\n```json\n{\n  \"mcpServers\": {\n    \"apify\": {\n      \"url\": \"https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper\",\n      \"headers\": { \"Authorization\": \"Bearer YOUR_APIFY_TOKEN\" }\n    }\n  }\n}\n```\n\n3. Open **Cursor → Settings → MCP** and confirm the **apify** server is connected (green dot).\n4. In Composer or Chat, ask Cursor to call the Google Hotels API.\n\nNew to Cursor? Get it here: https://cursor.com/referral?code=XQP4VBLI3NNX\n\n## Install in ChatGPT\n\n![Install in ChatGPT](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_ChatGPT.png)\n\nChatGPT connects to the Apify MCP server through Developer mode (available on ChatGPT Pro, Plus, Business, Enterprise, and Education plans).\n\n1. Click your profile icon, then go to **Settings > Apps**. If you do not see a **Create app** button, open **Advanced settings** and enable **Developer mode**.\n2. Click **Create app** and fill out the form:\n   - **Name:** Apify\n   - **MCP Server URL:** `https://mcp.apify.com/?tools=actors,docs,johnvc/google-hotels-search-scraper`\n   - **Authentication:** OAuth\n3. Click **Create** and authorize the connection with Apify.\n4. To use the app in a conversation, click **+** in the chat, choose **Developer mode**, and select **Apify**.\n\nMore help: https://docs.apify.com/platform/integrations/mcp\n\n---\n\n[**Made with care**](https://apify.com/johnvc?fpr=9n7kx3)\n\n*Use the Google Hotels API to power price monitoring, travel apps, and market research with reliable, structured results.*\n\nLast Updated: 2026.09.07\n",
  "bytes": 15708,
  "sha": "58616e093b472fd30d388c8e4b309692b733a1bc596f0e21715cc6f3af1a2fc5",
  "repo_slug": "johnisanerd/apify-google-hotels-api",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_johnisanerd_google_hotels_b47a1e7f/readme"
}