# Google Flights and Hotels Prices API (`jixiaohao/google-flights-hotels-prices`) Actor

Live Google Flights and Google Hotels prices: ranked flights with stops, layovers, CO2 and low/typical/high price insight, flexible dates, and hotel prices on every booking site with direct links. Pay per search, not per result. Works as an MCP server for AI agents.

- **URL**: https://apify.com/jixiaohao/google-flights-hotels-prices.md
- **Developed by:** [Ji](https://apify.com/jixiaohao) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 flight searches

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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 Flights & Hotels Prices API

Live prices from Google Flights and Google Hotels in one actor, shaped so an AI agent can act on the answer in a single call.

**Flights:** give it a route and dates; get ranked options with

- total price, airlines, departure and arrival times, duration
- stops and layovers (airport and connection time), each leg's flight number, aircraft and legroom
- CO2 estimate against the route's typical emissions
- the **cheapest, fastest and best** picks, and whether prices are currently **low, typical or high** with Google's typical range and price history
- optional **flexible dates** (±1 to 3 days) with the cheapest date pair

**Hotels:** give it a city, area or hotel name and dates; get

- hotels with nightly price (before and after taxes), total for the stay, star class, guest rating, review count and deals ("43% less than usual")
- for the top hotels, the **price on every booking site**: Booking.com, Expedia, Hotels.com, Agoda, the hotel's official site and more, cheapest first, with direct booking links
- search a hotel's name to compare booking sites for just that hotel

Dates, guests (adults and children's ages), cabin, passengers, currency and country are all honored. Google ignores plain `checkin=`/`adults=` URL parameters, so this actor encodes them the way Google's own pages do.

### Benchmark

On 26 Oct 2026 we ran the same searches through this actor and the most-used Google Flights and Google Hotels actors on the Store: 4 flight routes (JFK-LAX round trip, SFO-JFK, LHR-CDG, BOS-BZN with connections) and 3 hotel cities (Paris, New York, Tokyo, 2 nights). Every run of every actor succeeded.

**Hotels**

| | Searches OK | Avg run time | Hotels | Prices per booking site | Price per search |
| --- | --- | --- | --- | --- | --- |
| **This actor** | **3 / 3** | **8 s** | 20 | **Up to 9 sites per hotel, with booking links** (top 3 hotels) | **$0.020** |
| Most-used hotels actor | 3 / 3 | 9 s | 20 | None (one price per hotel) | free tier |
| Hotels actor with per-site prices | 3 / 3 | 18 s | 20 | Up to 7 sites | $0.15 |

**Flights**

| | Searches OK | Avg run time | Options | Price per search |
| --- | --- | --- | --- | --- |
| **This actor** | **4 / 4** | **5 s** | 10 by default, up to everything Google lists (`maxResults`), plus cheapest/fastest/best picks, price level and 60-day price history | **$0.005**, however many options |
| Most-used flights actor | 4 / 4 | 12 s | About 30 per page | about $0.001 |
| Second flights actor | 4 / 4 | 6 s | Up to the limit set | $0.001 per flight ($0.02 for 20) |

The script and inputs are in [`bench/`](bench/).

### Pricing

Pay per search, only when it returns data:

| Event | Price | When |
| --- | --- | --- |
| `flight-search` | $0.005 | One route and date pair with results. With `flexDays`, each extra date searched counts once. |
| `hotel-search` | $0.002 | One hotel search with results. |
| `hotel-prices` | $0.006 | One hotel compared across booking sites (`compareSites`, default 3). |

A flight search is one charge however many options it returns: 10 by default, or up to everything Google lists (often 15 to 60) with `maxResults`. A hotel search with the default settings (3 hotels compared) costs $0.020.

### Input

Pick a `mode` and fill in its fields. Dates default to 30 days from today.

| Field | Mode | Default | Notes |
| --- | --- | --- | --- |
| `mode` | | `flights` | `flights` or `hotels` |
| `origin`, `destination` | flights | | IATA airport or city code: `JFK`, `NYC`, `LHR`, `PAR` |
| `departureDate`, `returnDate` | flights | +30 days, one-way | `YYYY-MM-DD`; leave `returnDate` empty for one-way |
| `adults`, `children`, `infantsInSeat`, `infantsOnLap` | flights | 1, 0, 0, 0 | |
| `cabinClass` | flights | `economy` | `premium_economy`, `business`, `first` |
| `maxStops` | flights | any | `0` = nonstop only |
| `sortBy` | both | `best` / `relevance` | Flights: `price`, `duration`, `departure`. Hotels: `price`, `rating` |
| `flexDays` | flights | 0 | Also search ±N days (max 3) and return `dateGrid` + `cheapestDates` |
| `location` | hotels | | City, area or hotel name |
| `checkIn`, `checkOut` | hotels | +30 days, 2 nights | Up to 30 nights |
| `adults`, `childrenAges` | hotels | 2, none | e.g. `"childrenAges": [8, 11]` |
| `compareSites` | hotels | 3 | Top N hotels to price on every booking site; 0 to skip |
| `minRating`, `minHotelClass`, `maxPrice` | hotels | | Filters; `maxPrice` is nightly before taxes |
| `maxResults` | both | 10 / 20 | |
| `currency`, `country`, `language` | both | `USD`, `US`, `en` | |
| `searches` | both | | Batch: an array of searches, each with its own `mode` and fields. Free-plan runs are capped at 3. |
| `proxyConfiguration` | | Datacenter, then residential | Tries Apify's cheaper datacenter proxy first and switches to residential if Google blocks it |

#### Example: one flight search

```json
{
  "mode": "flights",
  "origin": "JFK",
  "destination": "LAX",
  "departureDate": "2026-12-10",
  "returnDate": "2026-12-17",
  "sortBy": "price",
  "flexDays": 1
}
```

#### Example: hotels plus a batch

```json
{
  "searches": [
    { "mode": "hotels", "location": "Paris", "checkIn": "2026-12-10", "checkOut": "2026-12-12", "adults": 2, "minRating": 4 },
    { "mode": "hotels", "location": "Hilton Paris Opera", "checkIn": "2026-12-10", "checkOut": "2026-12-12" },
    { "mode": "flights", "origin": "LHR", "destination": "CDG", "departureDate": "2026-12-10", "maxStops": 0 }
  ],
  "currency": "EUR"
}
```

### Output

One dataset item per search.

#### Flights (`type: "flightSearch"`)

```json
{
  "type": "flightSearch",
  "origin": "JFK", "destination": "LAX",
  "departureDate": "2026-12-10", "returnDate": "2026-12-17", "tripType": "roundTrip",
  "currency": "USD",
  "priceNote": "Prices are round-trip totals for all passengers; each option is an outbound flight, as Google Flights lists it.",
  "highlights": {
    "cheapest": { "price": 373, "airlines": "Delta", "stops": 0, "departure": "2026-12-10T09:00", "arrival": "2026-12-10T12:18", "durationMinutes": 378 },
    "fastest": { "...": "..." },
    "best": { "...": "..." }
  },
  "priceInsight": { "level": "typical", "typicalLow": 215, "typicalHigh": 550, "priceHistory": [{ "date": "2026-08-27", "price": 443 }] },
  "flights": [
    {
      "rank": 1, "price": 194, "airlines": ["United"], "departure": "2026-12-10T06:00", "arrival": "2026-12-10T11:33",
      "durationMinutes": 453, "stops": 1,
      "layovers": [{ "airport": "ORD", "airportName": "Chicago O'Hare International Airport", "durationMinutes": 59 }],
      "legs": [
        { "flightNumber": "UA 1414", "from": "BOS", "to": "ORD", "departure": "2026-12-10T06:00", "arrival": "2026-12-10T08:00", "aircraft": "Boeing 737MAX 9 Passenger", "legroom": "30 in" },
        { "flightNumber": "UA 224", "from": "ORD", "to": "BZN", "departure": "2026-12-10T08:59", "arrival": "2026-12-10T11:33", "aircraft": "Boeing 737", "legroom": "30 in" }
      ],
      "co2Kg": 294, "typicalCo2Kg": 316, "isBest": true
    }
  ],
  "googleFlightsUrl": "https://www.google.com/travel/flights/search?tfs=...",
  "errors": []
}
```

Times are local to each airport. For round trips, Google prices each outbound option as the round-trip total; the return flight is chosen on Google's next screen.

#### Hotels (`type: "hotelSearch"`)

```json
{
  "type": "hotelSearch",
  "location": "Paris", "checkIn": "2026-12-10", "checkOut": "2026-12-12", "nights": 2, "adults": 2, "currency": "USD",
  "hotels": [
    {
      "rank": 1, "name": "Glint Paris", "entityId": "ChcIhPDt-4LWsolAGgsvZy8xdjZsNnQ2bRAB",
      "hotelClass": null, "rating": 4.5, "reviewCount": 3311,
      "nightlyPrice": 64.03, "nightlyPriceWithTaxes": 76, "totalPriceWithTaxes": 152.49,
      "deal": "43% less than usual",
      "latitude": 48.8886, "longitude": 2.3498, "checkInTime": "3:00 PM", "checkOutTime": "11:00 AM",
      "cheapestSite": { "provider": "Booking.com", "nightlyPriceWithTaxes": 76.24, "totalPriceWithTaxes": 152.49 },
      "offers": [
        { "provider": "Booking.com", "nightlyPrice": 64.03, "nightlyPriceWithTaxes": 76.24, "totalPriceWithTaxes": 152.49, "bookingUrl": "https://www.booking.com/..." },
        { "provider": "Glint Paris", "isOfficialSite": true, "nightlyPriceWithTaxes": 122.08, "bookingUrl": "https://..." }
      ]
    }
  ],
  "hotelsCompared": 3,
  "errors": []
}
```

When a part fails (say, one hotel's booking-site prices), you still get the rest, with the reason in `errors`, and you are not charged for the part that failed.

### For AI agents (Standby + MCP)

The actor runs as a Standby web server:

- **MCP:** `https://jixiaohao--google-flights-hotels-prices.apify.actor/mcp` with tools `search_flights` and `search_hotels`. Add it to Claude or any MCP client with your Apify token (`?token=...` or a Bearer header). Tool results are compact by default (`detail: "summary"`: highlights and the top 5 options); pass `detail: "full"` for everything.
- **REST:** `GET /flights?origin=JFK&destination=LAX&departureDate=2026-12-10&returnDate=2026-12-17` and `GET /hotels?location=Paris&checkIn=2026-12-10&checkOut=2026-12-12`.

### How it works

The actor loads the same pages you see on google.com/travel through a proxy session it rotates with backoff whenever Google slows it down (datacenter first, residential if Google blocks it), and reads the structured data embedded in each page rather than its layout, so cosmetic page changes don't break it. Prices are what Google shows for the chosen country and currency at the time of the run; they change often and can differ slightly from the booking site's final checkout price.

### Development

```bash
npm install
npm test        # parsers and Standby server, against recorded Google pages in test/fixtures
```

`scripts/trim-fixture.mjs` turns a saved Google page into a small gzipped fixture.

# Actor input Schema

## `mode` (type: `string`):

Flights uses the Flights fields below; Hotels uses the Hotels fields.

## `origin` (type: `string`):

Airport or city code, e.g. JFK, NYC, LHR.

## `destination` (type: `string`):

Airport or city code, e.g. LAX, PAR, TYO.

## `departureDate` (type: `string`):

YYYY-MM-DD. Default: 30 days from today.

## `returnDate` (type: `string`):

YYYY-MM-DD. Leave empty for one-way. Round-trip prices are totals; each option is an outbound flight, as Google Flights lists it.

## `cabinClass` (type: `string`):

Cabin class for flights.

## `adults` (type: `integer`):

Flights: 1-9 (default 1). Hotels: 1-6 (default 2).

## `children` (type: `integer`):

Children aged 2-11 (flights).

## `infantsInSeat` (type: `integer`):

Infants under 2 with their own seat (flights).

## `infantsOnLap` (type: `integer`):

Infants under 2 on an adult's lap (flights).

## `maxStops` (type: `string`):

Maximum number of stops per direction (flights).

## `sortBy` (type: `string`):

Flights: best (Google's ranking), price, duration, departure. Hotels: relevance, price, rating.

## `flexDays` (type: `integer`):

Also search this many days before and after, shifting the return by the same amount, and report the cheapest dates. Each extra date is billed as one flight search.

## `location` (type: `string`):

City, area or a hotel's name, e.g. "Paris", "Shibuya, Tokyo", "Hilton Paris Opera". A hotel name returns that hotel with its price on every booking site.

## `checkIn` (type: `string`):

YYYY-MM-DD. Default: 30 days from today.

## `checkOut` (type: `string`):

YYYY-MM-DD, 1-30 nights after check-in. Default: 2 nights.

## `childrenAges` (type: `array`):

One age (0-17) per child.

## `compareSites` (type: `integer`):

For the first N hotels, fetch the price on each booking site (Booking.com, Expedia, Agoda, the official site...). Each hotel is billed as one hotel-prices event. 0 to skip.

## `minRating` (type: `string`):

Only hotels with at least this Google guest rating.

## `minHotelClass` (type: `integer`):

Only hotels with at least this many stars (1-5).

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

Before taxes, in the chosen currency.

## `maxResults` (type: `integer`):

Options returned per search. Default 10 for flights, 20 for hotels.

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

ISO code, e.g. USD, EUR, GBP, JPY.

## `country` (type: `string`):

Two-letter code. Prices and sites can differ by country.

## `language` (type: `string`):

Language code for Google pages, e.g. en, de, fr.

## `searches` (type: `array`):

Run several searches in one run. Each entry is an object with the same fields as above plus "mode", e.g. {"mode": "hotels", "location": "Rome", "checkIn": "2026-12-10", "checkOut": "2026-12-12"}. When set, the single-search fields are ignored except currency, country and language.

## `proxyConfiguration` (type: `object`):

Apify's datacenter proxy is tried first because it is cheaper; if Google blocks it, the run switches to residential automatically. Choosing residential here skips the datacenter attempt.

## `maxRetries` (type: `integer`):

Retries per Google request, each on a fresh proxy session.

## Actor input object example

```json
{
  "mode": "flights",
  "origin": "JFK",
  "destination": "LAX",
  "cabinClass": "economy",
  "children": 0,
  "infantsInSeat": 0,
  "infantsOnLap": 0,
  "maxStops": "any",
  "sortBy": "best",
  "flexDays": 0,
  "compareSites": 3,
  "minRating": "0",
  "currency": "USD",
  "country": "US",
  "language": "en",
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "maxRetries": 5
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

## `results` (type: `string`):

No description

# 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 = {
    "mode": "flights",
    "origin": "JFK",
    "destination": "LAX",
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("jixiaohao/google-flights-hotels-prices").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 = {
    "mode": "flights",
    "origin": "JFK",
    "destination": "LAX",
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("jixiaohao/google-flights-hotels-prices").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 '{
  "mode": "flights",
  "origin": "JFK",
  "destination": "LAX",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call jixiaohao/google-flights-hotels-prices --silent --output-dataset

```

## MCP server setup

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

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/gtaVphJkfcvtsbSLv/builds/GJxtBncjx4PJ2l3lo/openapi.json