# Google Flights API: Prices, Itineraries & Date Grid (`ocius-data/google-flights-prices`) Actor

Google Flights prices API: one-way and round-trip itineraries with airlines, stops, times, emissions and prices in any currency, plus a cheapest-price-per-day grid. Pay per flight.

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

## Pricing

from $1.00 / 1,000 flight itineraries

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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 API: Prices, Itineraries & Date Grid

Get Google Flights prices for any route and dates: **airlines, flight numbers, departure and arrival times, duration, stops, layovers, CO2 emissions and the price in your currency**. Search one-way or round trip, get the **exact outbound and return flight pairs** with their total price, or use the **date grid** to find the cheapest day to fly in a range of up to 62 days. You pay **only per itinerary saved**. Searches without flights and failed requests are free.

### Why this Google Flights scraper

- **Fast and inexpensive.** No browser. A search returns in 1 to 3 seconds, and a 31-day date grid completes in about 11 seconds.
- **Reliable by design.** Each blocked request is retried with exponential backoff and a new IP address. Google sometimes answers datacenter IP addresses with a page that leaves the results out; the Actor detects it, retries at once and moves that request, and the run if it repeats, to residential proxies in your market country.
- **Airport codes or city names.** Type `JFK` or `New York`, `BOG` or `Bogotá`. A city searches all of its airports, exactly as on the Google Flights website. If Google interprets a city name as a different place, the search stops with a clear message instead of returning flights you did not ask for.
- **Round trips done properly.** By default, each outbound flight comes with Google's round-trip total. Turn on **Include return flights** to get each outbound and return pair with the details of both flights and the exact total for that pair.
- **Verified before you pay.** Every row is checked against the search Google answered: dates, currency, stops filter and flight numbers. Rows that do not match are discarded and not charged.
- **Clear status.** Every search ends as `OK`, `NO_RESULTS`, `BLOCKED`, `ERROR`, `INVALID_INPUT`, `TIMEOUT` or `NOT_PROCESSED`, with the reason in the `RUN_SUMMARY` record. If more than 20% of searches fail, the run is marked as failed so you notice.
- **Safe on long runs.** A search is marked as done in the same step that saves its rows, and saving pauses while the platform moves the run to another server, so a restart does not duplicate rows or charges.

### What data you get

| Group | Fields |
|---|---|
| Itinerary | Airlines, airline codes, flight numbers, departure and arrival airport, date and time, total duration, number of stops, Google's "best flights" flag |
| Layovers | Airport, city, duration and whether you change airports |
| Each flight leg | Flight number, airline, airports with names, times, duration, aircraft, legroom, codeshare flight numbers, CO2 |
| Price | Total price for all passengers, currency, price type (one-way or round-trip total), passengers, cabin |
| Emissions | CO2 in kg, typical CO2 for the route, percentage versus typical, level (`lower`, `typical`, `higher`) |
| Return flight | With **Include return flights**: the full details of the return flight in each pair |
| Date grid | Cheapest price per departure date, number of options, nonstop availability and cheapest nonstop price, the cheapest flight's details |
| Traceability | `googleFlightsUrl` (opens Google Flights with the flight selected and the booking options), `sourceUrl`, the input used and `scrapedAt` on every row |

The output tab has an itineraries table and a date-grid table. Download as JSON, CSV or Excel, or connect through the API.

### How to use it

1. Enter **From** and **To**: an airport code (`JFK`) or a city (`New York`, `Paris, France`).
2. Set the **departure date** (leave it empty to search 30 days from today) and, for a round trip, the **return date**.
3. Choose **adults**, **children**, **cabin class** and **stops**.
4. Choose the **currency**, **language** and **country** (the market you search from).
5. Optional: add more routes or dates in **More searches**.
6. Optional: turn on **Include return flights** for outbound and return pairs, or **Date grid** for the cheapest price per day.
7. Run the Actor.

#### Input example: one-way and round trip

```json
{
  "origin": "JFK",
  "destination": "LAX",
  "departureDate": "2026-12-10",
  "searches": [
    { "origin": "Bogotá", "destination": "Madrid, Spain", "departureDate": "2026-12-10", "returnDate": "2026-12-20" }
  ],
  "adults": 2,
  "cabinClass": "economy",
  "maxStops": "any",
  "currency": "USD",
  "country": "US",
  "maxResults": 50
}
```

#### Input example: date grid

```json
{
  "origin": "MEX",
  "destination": "Cancún",
  "dateGrid": true,
  "dateGridStart": "2026-12-01",
  "dateGridEnd": "2026-12-31",
  "tripLengthDays": 5,
  "currency": "MXN"
}
```

Leave `tripLengthDays` empty for one-way prices.

### Example output

```json
{
  "origin": "CLO",
  "destination": "MIA",
  "tripType": "round_trip",
  "position": 1,
  "isBestFlight": true,
  "airlines": ["COPA"],
  "flightNumbers": ["CM 322", "CM 226"],
  "departureAirport": "CLO",
  "arrivalAirport": "MIA",
  "departureDate": "2026-12-10",
  "departureTime": "04:38",
  "arrivalDate": "2026-12-10",
  "arrivalTime": "11:25",
  "durationMinutes": 407,
  "stops": 1,
  "layovers": [
    { "airport": "PTY", "airportName": "Tocumen International Airport Panama", "city": "Panama City", "durationMinutes": 122, "changeOfAirport": false, "nextDepartureAirport": "PTY" }
  ],
  "emissions": { "co2Kg": 218, "typicalCo2Kg": 238, "percentVsTypical": -8, "level": "lower" },
  "legs": [
    { "flightNumber": "CM 322", "airline": "COPA", "departureAirport": "CLO", "arrivalAirport": "PTY", "departureTime": "04:38", "arrivalTime": "06:14", "durationMinutes": 96, "aircraft": "Boeing 737", "legroom": "31 inches", "alsoSoldAs": ["UA 7081"], "co2Grams": 79973 }
  ],
  "price": 1893330,
  "currency": "COP",
  "priceType": "round_trip_total",
  "passengers": 1,
  "cabinClass": "economy",
  "returnDate": "2026-12-17",
  "googleFlightsUrl": "https://www.google.com/travel/flights/search?tfs=...&hl=en&gl=co&curr=COP",
  "scrapedAt": "2026-11-01T23:56:50.347Z"
}
```

A date-grid row:

```json
{
  "origin": "MEX",
  "destination": "Cancún",
  "destinationResolved": "/m/01q98m",
  "destinationName": "Cancún",
  "tripType": "round_trip",
  "departureDate": "2026-12-03",
  "returnDate": "2026-12-08",
  "price": 2931,
  "currency": "MXN",
  "priceType": "round_trip_total",
  "optionsFound": 24,
  "nonstopAvailable": true,
  "cheapestNonstopPrice": 2931,
  "cheapestFlight": { "airlines": ["Viva"], "flightNumbers": ["VB 1038"], "departureTime": "19:20", "arrivalTime": "22:25", "arrivalDate": "2026-12-03", "durationMinutes": 125, "stops": 0 }
}
```

### Pricing

Pay per event, no monthly fee:

| Event | Price | When it is charged |
|---|---|---|
| `flight` | **USD 0.001** per itinerary (USD 1 per 1,000) | Each itinerary saved with a price. With **Include return flights**, each outbound and return pair is one itinerary. |
| `date-price` | **USD 0.01** per date (USD 10 per 1,000) | Each departure date saved with a price in **Date grid** mode. |

Searches without flights, invalid input, blocked requests, duplicates and rows that fail validation are not charged. Your maximum cost per run is respected: rows beyond it are neither saved nor charged, and the summary says how many were found but not saved.

| Run | Rows | Approximate cost |
|---|---|---|
| One route, one date, 30 itineraries | 30 | USD 0.03 |
| Daily price check on 20 routes, 25 itineraries each | 500 | USD 0.50 |
| Round trip with return flights, 10 pairs | 10 | USD 0.01 |
| Cheapest day in a 31-day window | 31 | USD 0.31 |

### Output fields

| Field | Meaning | When it is null or absent |
|---|---|---|
| `origin`, `destination` | What you entered. | Never |
| `originResolved`, `destinationResolved` | The airport code or Google city ID searched. | Never |
| `originName`, `destinationName` | The city name Google matched, for city searches. | Absent for airport codes |
| `tripType` | `one_way` or `round_trip`. | Never |
| `position`, `isBestFlight` | Order in Google's results and whether Google lists it under "Best flights". | Not in date grid rows |
| `airlines`, `airlineCodes`, `flightNumbers` | Marketing airlines and flight numbers, in flight order. | Never |
| `departureAirport`, `departureDate`, `departureTime` | Where and when the itinerary starts (local time). | Never |
| `arrivalAirport`, `arrivalDate`, `arrivalTime` | Where and when it ends (local time). `arrivalDate` shows overnight arrivals. | Never |
| `durationMinutes`, `stops` | Total travel time and number of stops. | Never |
| `layovers` | One entry per stop: airport, city, duration, change of airport. | Empty list for nonstop flights |
| `legs` | Each flight: number, airline, airports, times, duration, aircraft, legroom, codeshares (`alsoSoldAs`), CO2 in grams. | `aircraft`, `legroom` when Google has no value |
| `emissions` | CO2 for the itinerary and versus the route's typical value. | When Google shows no estimate |
| `price`, `currency` | Lowest price Google shows, total for all passengers, taxes included. | Never (rows without a price are not saved) |
| `priceType` | `one_way_total` or `round_trip_total`. For round trips without return flights, the price is Google's lowest round-trip total starting with that outbound flight. | Never |
| `passengers`, `cabinClass`, `returnDate` | The search Google priced. | `returnDate` on one-way rows |
| `returnFlight` | The return flight, with the same fields as the outbound itinerary. | Only with **Include return flights** |
| `optionsFound`, `nonstopAvailable`, `cheapestNonstopPrice`, `cheapestFlight` | Date grid details. | Only in date grid rows; `cheapestNonstopPrice` is null without nonstop flights |
| `googleFlightsUrl` | Opens Google Flights with this flight (or pair) selected and its booking options. | Never |
| `sourceUrl` | The results page the row came from. | Never |
| `input` | The search and options used. | Never |
| `scrapedAt` | When the data was collected (UTC). | Never |

### Statuses and errors

| Status | Meaning | What to do |
|---|---|---|
| `OK` | At least one row saved. The summary explains if fewer than `maxResults` were saved. | Nothing |
| `NO_RESULTS` | Google shows no priced flight for this route, date and filters. Not charged. | Change the date, relax the stops filter or try nearby airports. |
| `BLOCKED` | Google kept blocking after all retries and proxy escalation. Not charged. | Run again later or select residential proxies. |
| `ERROR` | Google returned an unexpected page. Not charged. | Report it; the page format may have changed. |
| `INVALID_INPUT` | For example, an unknown airport code, a city Google could not match, or a currency Google does not support. Not charged. | Fix the input as the message says. |
| `TIMEOUT` | The run reached its timeout before this search. | Increase the run timeout. |
| `NOT_PROCESSED` | Your maximum cost per run was reached before this search. | Raise the maximum cost per run. |

Input errors such as a date in the past, a return before the departure, more than 9 passengers or a date grid longer than 62 days stop the run within seconds with a message that says how to fix them.

### Known limits

- Prices change constantly and depend on the market (`country`), currency and moment of the search, as on Google Flights itself. The booking page can show a slightly different final price.
- The Actor returns the itineraries Google lists on its results page, usually between 5 and 100 per search.
- Infants (on lap or in seat) are not supported: Google does not price them on the results page. Adults and children up to 9 passengers in total are supported.
- Baggage fees and fare families (basic, main, flex) are shown only on Google's booking page and are not included.
- Prices are totals for all passengers. Divide by `passengers` for an average per person; child fares can differ from adult fares.
- Multi-city trips are not supported.

### How it works

The Actor requests the same pages as the Google Flights website and reads the data Google embeds in them. Routes, dates, passengers, cabin and stops are encoded in the `tfs` URL parameter the website itself uses, and Google's answer is checked against the search sent. City names are matched to Google's own place IDs with Google's natural-language search. No browser is used, which keeps runs fast and inexpensive.

### Current status

No incidents. Operational issues are posted here.

### Integrations: API, schedules, webhooks, Google Sheets and AI agents

**API.** Run the Actor and receive the itineraries in one call:

```bash
curl -X POST "https://api.apify.com/v2/acts/ocius-data~google-flights-prices/run-sync-get-dataset-items?token=YOUR_API_TOKEN&format=json"   -H "Content-Type: application/json"   -d '{"origin": "BOG", "destination": "MIA", "departureDate": "2026-12-15", "returnDate": "2026-12-22", "currency": "USD"}'
```

Python, with the official `apify-client` package:

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_API_TOKEN")
run = client.actor("ocius-data/google-flights-prices").call(run_input={"origin": "JFK", "destination": "LHR", "departureDate": "2026-12-10", "maxStops": "nonstop"})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["price"], row["currency"], row["airlines"], row["departureTime"], row["stops"])
```

**Schedules.** Save your input as a task and open **Schedules** in Apify Console to check the same routes and dates every day and build a fare history. Use the date grid to watch the cheapest day of a whole month in one run.

**Webhooks, Google Sheets, Zapier, Make and n8n.** In the task, open **Integrations** and add a webhook for `ACTOR.RUN.SUCCEEDED`, the Google Sheets integration, or the official Apify app in Zapier, Make or n8n (trigger "Actor run finished", action "Get dataset items").

**MCP and AI agents.** The Actor is available through the Apify MCP server (`https://mcp.apify.com`). Add `ocius-data/google-flights-prices` to the server's Actor list and an AI agent such as Claude can call it with plain inputs such as `{"origin": "MAD", "destination": "BCN", "departureDate": "2026-12-20"}`.

### FAQ

**Is it legal?** The Actor collects publicly available flight schedules and prices. It does not collect personal data. Check the rules that apply to your use case.

**Why do prices differ from what I see?** Set the same passengers, cabin, currency and country. Google adjusts prices by market, and airlines update fares many times a day.

**Can I track a route every day?** Yes. Schedule the Actor and compare `price` by `flightNumbers` and `departureDate` over time. The date grid is the cheapest way to watch a whole month.

**What happens if I am charged for a wrong price?** Open an issue with the run ID. Every case is reviewed, and confirmed defects are fixed with priority.

### Related Actors from ocius-data

Built to the same standard: a status for every input in `RUN_SUMMARY`, actionable error messages and list-based inputs, so they chain well in one workflow:

- **[Google Hotels Prices API: OTA Rates by Date](https://apify.com/ocius-data/google-hotels-reliable)**: hotel prices per night and per booking site for any city and dates.

### Changelog

- **0.1.7** (November 2026) When no departure date is given, the search uses the date 30 days from today, so the default input always runs.
- **0.1** First version: one-way and round trip, airport codes and city names, passengers and cabin, stops filter, currency, language and market, return flight pairs, date grid, statuses and run summary, proxy escalation.

### Use cases

- Fare monitoring and price alerts for routes and dates
- Travel agencies and corporate travel teams comparing airlines and schedules
- Flexible-date search: the cheapest day to fly in a month
- Route and capacity research: which airlines fly nonstop, with which aircraft
- Sustainability reporting with CO2 estimates per itinerary

### Tips

- For daily monitoring, keep the same currency and country, and compare by `flightNumbers` and `departureDate`.
- Use airport codes for exact airports, or a city to include all its airports. Add the country to ambiguous city names, for example `Cartagena, Colombia`.
- **Include return flights** opens one extra page per outbound flight. Set `maxResults` to the number of pairs you need.
- Sort date grid rows by `departureDate` or `price`; they are saved in completion order.

### Support

Open an issue on the Actor page. Issues are reviewed every business day; the first response arrives within 24 business hours and critical failures are fixed or worked around within 72 hours.

# Actor input Schema

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

Airport code (JFK, BOG, MAD) or city ("New York", "Bogotá", "Paris, France"). A city searches all of its airports.

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

Airport code or city, as in "From".

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

Format YYYY-MM-DD. Up to about 330 days ahead. Leave empty to search 30 days from today. Not used in date grid mode.

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

Optional. Leave empty for a one-way search. With a return date, prices are round-trip totals.

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

Several routes or dates in one run. Each item: {"origin": "BOG", "destination": "MAD", "departureDate": "2026-12-10", "returnDate": "2026-12-20"}. Up to 100 searches. Passenger, cabin and currency options apply to all of them.

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

Passengers aged 12 or older.

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

Passengers aged 2 to 11. Adults plus children: up to 9. Prices are totals for all passengers.

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

Cabin to price.

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

Filter by number of stops.

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

ISO currency code for all prices, for example USD, EUR, GBP, COP, MXN or BRL.

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

Language of airline and airport names, for example en, es, pt-BR or fr.

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

Two-letter code of the market you search from, for example US, CO, ES or MX. Fares can differ by market.

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

Upper limit of itineraries saved (and charged) per search. Google usually shows between 5 and 100 per search.

## `includeReturnFlights` (type: `boolean`):

Off: one row per outbound flight with Google's round-trip total price. On: one row per outbound and return flight pair, with both flights' details and the exact total for that pair. Each pair is one itinerary.

## `maxReturnOptions` (type: `integer`):

With return flights on: how many return options to keep for each outbound flight, in Google's order.

## `dateGrid` (type: `boolean`):

On: instead of itineraries, get the cheapest price for each departure date in a range. Charged per date with a price (event "date-price").

## `dateGridStart` (type: `string`):

Date grid only. Format YYYY-MM-DD.

## `dateGridEnd` (type: `string`):

Date grid only. Up to 62 days after the first date.

## `tripLengthDays` (type: `integer`):

Date grid only. Leave empty for one-way prices. With a value, each date is priced as a round trip returning this many days later.

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

By default the Actor starts with datacenter proxies and switches to residential proxies in your market country if Google blocks requests.

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

Each blocked request is retried with a new IP address and exponential backoff.

## `maxConcurrency` (type: `integer`):

Requests sent to Google at the same time.

## Actor input object example

```json
{
  "origin": "JFK",
  "destination": "LAX",
  "searches": [],
  "adults": 1,
  "children": 0,
  "cabinClass": "economy",
  "maxStops": "any",
  "currency": "USD",
  "language": "en",
  "country": "US",
  "maxResults": 50,
  "includeReturnFlights": false,
  "maxReturnOptions": 3,
  "dateGrid": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "maxRetries": 6,
  "maxConcurrency": 3
}
```

# Actor output Schema

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

One row per itinerary (flights mode) or per departure date (date grid mode).

## `runSummary` (type: `string`):

Status per search (OK, NO_RESULTS, BLOCKED, ERROR, INVALID_INPUT, TIMEOUT, NOT_PROCESSED), field completeness, memory and charge reconciliation.

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

// Run the Actor and wait for it to finish
const run = await client.actor("ocius-data/google-flights-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 = {
    "origin": "JFK",
    "destination": "LAX",
}

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

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ocius-data/google-flights-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/egkf5taqSIaYBBwcX/builds/Pd66ismAiITnpWLAq/openapi.json