# Google Hotels Search API - Prices & Booking Sources (`gauravlabs/google-hotels-api`) Actor

Search Google Hotels prices, ratings, amenities and locations. Paginate without duplicates, export CSV-ready hotel rows, and compare booking-site offers.

- **URL**: https://apify.com/gauravlabs/google-hotels-api.md
- **Developed by:** [Gaurav Kumar Choudhary](https://apify.com/gauravlabs) (community)
- **Categories:** Travel, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.20 / 1,000 successful hotel searches

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Google Hotels Search API — Prices & Booking Sources

Search Google Hotels for hotel prices, ratings, amenities, locations and images. Collect multiple pages without duplicate properties, export one hotel per row, and optionally compare booking-site offers.

### Quick start

```json
{
  "query": "Paris hotels",
  "checkInDate": "+14d",
  "checkOutDate": "+16d",
  "currency": "EUR",
  "limit": 20,
  "maxPages": 2,
  "maxHotels": 30,
  "outputMode": "hotels",
  "includeBookingSources": true,
  "maxDetails": 3
}
```

Other destination examples: `New York hotels`, `Dubai hotels`, `Goa hotels`, or `hotels near JFK airport`. Use a city or landmark query—not an airport code alone. Dates accept `YYYY-MM-DD` or relative values such as `+14d`, resolved on the run date in UTC. Check-out must be after check-in.

### Features and controls

- Pagination with duplicate removal by property name and coordinates. `maxPages` and `maxHotels` cap collection; `limit` is the page size (1–20).
- Optional booking-source enrichment: `includeBookingSources` looks up the first `maxDetails` properties with available detail tokens.
- Export-friendly rows with `pricePerNight`, `totalPrice`, `currency`, `rating`, coordinates and dates. Missing prices remain null; `isPriced` distinguishes unavailable prices from real rates.
- Destination, language, country and currency controls; price, hotel class, rating, amenities, property-type, free-cancellation, eco-certified and special-offer filters.
- `sortBy`: 0 relevance (default), 3 lowest price, 8 highest rating, 13 most reviews.
- Run charge limits stop additional requests. If an optional booking lookup fails, the listing results are preserved with a warning.

Prices use **2 adults and 0 children**. Custom occupancy is not supported. Availability, vendor offers and prices vary by destination, dates and market. Not every property has a price or booking offers. This Actor does not make reservations or guarantee rates, availability or exhaustive inventory.

### Outputs

`outputMode: "hotels"` stores one row per hotel in the dataset for JSON, CSV or Excel exports. `outputMode: "summary"` stores one response object containing `properties`, `pagination`, `search_parameters`, `search_information` and `warnings`.

The complete response is always saved as the key-value store record `OUTPUT`. Output tabs link directly to the dataset and response. `search_information.successful_requests` reports billable successful requests; `pages_fetched` counts listing pages and `total_results` counts unique properties.

### Booking offers for one property

Copy a `detail_token` from a listing result and use the same dates, currency and locale:

```json
{
  "detailToken": "TOKEN_FROM_A_LISTING_RESULT",
  "checkInDate": "+14d",
  "checkOutDate": "+16d",
  "currency": "EUR"
}
```

The response includes `property.booking_sources`, with available booking vendors and rates. A property detail request is one billable successful request.

### Pricing

Pay per **successful request**, not per hotel row. Each successful listing page or property-offer lookup costs $0.0015 on Free, $0.0014 on Bronze, $0.0013 on Silver, and $0.0012 on Gold, Platinum or Diamond—the same request pricing as our Flights Actor. That is $1.50 to $1.20 per 1,000 successful requests, depending on your Apify plan. Check the Store pricing panel for current rates.

Example: two listing pages and three booking-source lookups are five successful requests: $0.0075 at the Free rate. A valid response with no hotels is still a successful request. Failed search requests do not trigger the successful-request charge. Setting `maxDetails: 0` or disabling enrichment avoids detail lookup charges. Set your run maximum charge in Apify to control spending.

### API and scheduling

Use the Actor's API tab to generate authenticated calls for your account. For a synchronous JSON response, POST your input to `https://api.apify.com/v2/acts/gauravlabs~google-hotels-api/run-sync-get-dataset-items` with your Apify authorization header. For larger jobs, start an asynchronous run, then download its dataset after completion. Relative dates work well with recurring Apify schedules.

### Troubleshooting

`INVALID_INPUT`: fix the query, dates or filter values described in the message. `SEARCH_UNAVAILABLE`: retry later or try a simpler destination query. No private authentication values are returned in outputs or failure messages. Use the Actor's Issues tab for support and include the run URL and non-sensitive input.

This is an independent data extraction tool, not affiliated with or endorsed by Google.

# Actor input Schema

## `query` (type: `string`):

Use Paris hotels, Delhi hotels, Dubai hotels or Tokyo hotels. Simple city queries work best.

## `checkInDate` (type: `string`):

YYYY-MM-DD or relative to today, e.g. +14d. Today or later.

## `checkOutDate` (type: `string`):

YYYY-MM-DD or relative to today, e.g. +16d. Must be after check-in.

## `outputMode` (type: `string`):

hotels gives one export-ready row per hotel. summary preserves the original search response. OUTPUT always contains the full result.

## `maxPages` (type: `integer`):

Auto-pagination cap. Each successfully retrieved page is charged once. Default 1; up to 50.

## `maxHotels` (type: `integer`):

Stop after this many unique hotels; multiple pages may be required.

## `includeBookingSources` (type: `boolean`):

Fetch per-vendor offers after listing. Each successful hotel detail lookup adds one request charge.

## `maxDetails` (type: `integer`):

Limits extra detail requests when booking-site prices are enabled.

## `detailToken` (type: `string`):

Optional token from a previous listing result. When supplied, retrieves booking offers for that property.

## `hl` (type: `string`):

Language code for returned content, e.g. en.

## `gl` (type: `string`):

Country code used for local results, e.g. us.

## `currency` (type: `string`):

Currency code for prices, e.g. USD.

## `sortBy` (type: `integer`):

0: relevance, 3: lowest price, 8: highest rating, 13: most reviewed.

## `minPrice` (type: `integer`):

Optional minimum nightly price in the selected currency.

## `maxPrice` (type: `integer`):

Optional maximum nightly price in the selected currency.

## `rating` (type: `integer`):

Optional minimum rating: 7, 8, or 9.

## `hotelClass` (type: `string`):

Optional comma-separated star ratings, for example 4,5.

## `amenities` (type: `string`):

Optional comma-separated amenity codes, for example 22 for a pool.

## `propertyTypes` (type: `string`):

Optional comma-separated property type codes; use 12 for vacation rentals.

## `freeCancellation` (type: `boolean`):

Only return properties with free cancellation.

## `ecoCertified` (type: `boolean`):

Only return eco-certified properties.

## `specialOffers` (type: `boolean`):

Only return properties with special offers.

## `nextPageToken` (type: `string`):

Optional pagination token from the previous listing response.

## `limit` (type: `integer`):

Maximum listing results to return (1-20).

## Actor input object example

```json
{
  "query": "Paris hotels",
  "checkInDate": "+14d",
  "checkOutDate": "+16d",
  "outputMode": "summary",
  "maxPages": 1,
  "maxHotels": 20,
  "includeBookingSources": false,
  "maxDetails": 5,
  "hl": "en",
  "gl": "us",
  "currency": "USD",
  "sortBy": 0,
  "freeCancellation": false,
  "ecoCertified": false,
  "specialOffers": false,
  "limit": 20
}
```

# Actor output Schema

## `hotels` (type: `string`):

Hotel rows or a search response, depending on outputMode.

## `response` (type: `string`):

Complete search result, pagination, counters and warnings.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "Paris hotels",
    "checkInDate": "+14d",
    "checkOutDate": "+16d"
};

// Run the Actor and wait for it to finish
const run = await client.actor("gauravlabs/google-hotels-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "query": "Paris hotels",
    "checkInDate": "+14d",
    "checkOutDate": "+16d",
}

# Run the Actor and wait for it to finish
run = client.actor("gauravlabs/google-hotels-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "Paris hotels",
  "checkInDate": "+14d",
  "checkOutDate": "+16d"
}' |
apify call gauravlabs/google-hotels-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gauravlabs/google-hotels-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/CAAASv87pCX8DK8WD/builds/dNaAPKJ9cCZGDU2A6/openapi.json