# Google Flights Api (`ilborso/google-flights-api`) Actor

Search Google Flights for fares, durations, layovers, airlines, carbon emissions, and price insights. The actor returns structured JSON with detailed flight itineraries, booking tokens, and airport metadata — pushed directly to an Apify Dataset.

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

## Pricing

from $1.90 / 1,000 results

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 Search — Apify Actor

Search **Google Flights** for fares, durations, layovers, airlines, and carbon emissions. The actor returns structured JSON with detailed flight itineraries and booking tokens — pushed directly to an Apify Dataset.

This actor queries Google's flight search engine and returns the same fare list, durations, layovers, airlines, and emission data that Google shows in the Flights UI — as clean, structured JSON.

***

### Key Features

- **Structured JSON Output**: Full JSON response containing `search_parameters`, `best_flights[]`, `other_flights[]`, `price_insights`, and `airports[]`.
- **Round Trip & One Way**: Round trips with `return_date`, one-way searches by default.
- **Multi-Airport Origin/Destination**: Comma-separated IATA codes for multi-airport searches (e.g. `JFK,LGA,EWR`).
- **Carbon Emissions**: Per-itinerary `carbon_emissions` block with `this_flight`, `typical_for_this_route`, and `difference_percent`.
- **Price Insights**: Comprehensive `price_insights` with `lowest_price`, `price_level` (low / typical / high), `typical_price_range`, and `price_history`.
- **Sort Modes**: 6 sorting options — top, price, departure, arrival, duration, or emissions.
- **Cabin & Stop Filters**: Filter by `travel_class` (economy / premium / business / first), `stops` (any / nonstop / ≤1 / ≤2), and airline inclusion/exclusion.
- **Localization**: `hl`, `gl`, and `currency` for full regional pricing (EUR, GBP, JPY, TRY, etc.).

***

### Input Parameters

#### Required

| Parameter | Type | Description |
|---|---|---|
| `departure_id` | string | Origin IATA code (e.g. `JFK`). Comma-separated for multi-airport origin (e.g. `JFK,LGA,EWR`). |
| `arrival_id` | string | Destination IATA code. Same multi-airport rules as `departure_id`. |
| `outbound_date` | string | Departure date in `YYYY-MM-DD` format. Must be today or a future date. |

#### Trip Type

| Parameter | Type | Default | Description |
|---|---|---|---|
| `type` | integer | auto | `1` = round trip (requires `return_date`), `2` = one way. Auto-inferred from `return_date`. |
| `return_date` | string | — | Return date in `YYYY-MM-DD` format. Required when `type=1`. Must be on or after `outbound_date`. |

#### Passengers

| Parameter | Type | Default | Description |
|---|---|---|---|
| `adults` | integer | `1` | Number of adults (1–9). |
| `children` | integer | `0` | Number of children (0–9). |
| `infants_in_seat` | integer | `0` | Number of infants in seat (0–4). |
| `infants_on_lap` | integer | `0` | Number of infants on lap (0–4). |

#### Cabin & Filters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `travel_class` | integer | `1` | `1` = economy, `2` = premium economy, `3` = business, `4` = first. |
| `stops` | integer | `0` | `0` = any, `1` = nonstop, `2` = ≤1 stop, `3` = ≤2 stops. |
| `sort_by` | integer | `1` | `1` = top, `2` = price, `3` = departure, `4` = arrival, `5` = duration, `6` = emissions. |
| `include_airlines` | string | — | Comma-separated IATA airline codes (e.g. `DL,B6,AA`). Mutually exclusive with `exclude_airlines`. |
| `exclude_airlines` | string | — | Comma-separated IATA airline codes. Mutually exclusive with `include_airlines`. |
| `show_hidden` | boolean | `false` | When `true`, appends itineraries hidden behind "View more flights" to `other_flights`. |

#### Localization

| Parameter | Type | Default | Description |
|---|---|---|---|
| `hl` | string | `en` | Language code (ISO 639-1). |
| `gl` | string | `us` | Country code (ISO 3166-1 alpha-2). |
| `currency` | string | `USD` | Currency code (e.g. `EUR`, `GBP`, `JPY`, `TRY`). |

#### Example Input

**Simple one-way search:**

```json
{
    "departure_id": "JFK",
    "arrival_id": "LAX",
    "outbound_date": "2026-12-15"
}
```

**Round trip, two adults, business class, EUR:**

```json
{
    "departure_id": "IST",
    "arrival_id": "LHR",
    "outbound_date": "2026-12-01",
    "return_date": "2026-12-15",
    "type": 1,
    "adults": 2,
    "travel_class": 3,
    "currency": "EUR",
    "gl": "gb"
}
```

**Nonstop, cheapest first:**

```json
{
    "departure_id": "SFO",
    "arrival_id": "NRT",
    "outbound_date": "2026-12-10",
    "stops": 1,
    "sort_by": 2
}
```

**Include Hidden Itineraries** \*\*

```json
{
  "adults": 1,
  "arrival_id": "LHR",
  "currency": "USD",
  "departure_id": "IST",
  "gl": "us",
  "hl": "en",
  "outbound_date": "2026-12-10",
  "return_date": "2026-12-17",
  "show_hidden": true,
  "sort_by": "3",
  "travel_class": "2",
  "type": "1",
  "children": 0,
  "infants_in_seat": 0,
  "infants_on_lap": 0,
  "stops": "0"
}
```

**Multi-Airport Origin (NYC)**

```json
{
  "adults": 1,
  "arrival_id": "LAX",
  "currency": "USD",
  "departure_id": "JFK,LGA,EWR",
  "gl": "us",
  "hl": "en",
  "outbound_date": "2026-12-15",
  "show_hidden": true,
  "sort_by": "3",
  "travel_class": "1",
  "type": "2",
  "children": 0,
  "infants_in_seat": 0,
  "infants_on_lap": 0,
  "stops": "0"
}
```

**Filter by Airlines**

```json
{
  "arrival_id": "LAX",
  "currency": "USD",
  "departure_id": "JFK",
  "gl": "us",
  "hl": "en",
  "include_airlines": "DL,B6",
  "outbound_date": "2026-12-15",
  "show_hidden": false,
  "type": "2",
  "adults": 1,
  "children": 0,
  "infants_in_seat": 0,
  "infants_on_lap": 0,
  "travel_class": "1",
  "stops": "0",
  "sort_by": "1"
}
```

### Output Structure

The actor pushes the **full JSON response** directly from the Google Flights scraped service to the Apify Dataset. The top-level structure is:

#### Top-Level Fields

| Field | Type | Description |
|---|---|---|
| `search_parameters` | object | Echo of request parameters (`engine`, `type`, `departure_id`, `arrival_id`, `outbound_date`, `currency`, `gl`, `hl`, etc.). |
| `best_flights` | array | Top-ranked flight itineraries selected by Google Flights. |
| `other_flights` | array | Additional flight itineraries. |
| `price_insights` | object | Aggregate price insights (`lowest_price`, `price_level`, `typical_price_range`, `price_history`). |
| `airports` | array | Airport metadata for departure and arrival locations. |

***

#### `best_flights[]` and `other_flights[]`

Each entry is an **Itinerary** object:

| Field | Type | Description |
|---|---|---|
| `flights[]` | array | Per-segment flight details (`departure_airport`, `arrival_airport`, `duration`, `airplane`, `airline`, `airline_logo`, `travel_class`, `flight_number`, `legroom`, `extensions`, `overnight`). |
| `layovers[]` | array | Stops between segments (`duration`, `name`, `id`, `overnight`). |
| `total_duration` | integer | End-to-end duration in minutes including layovers. |
| `carbon_emissions` | object | Emissions block (`this_flight`, `typical_for_this_route`, `difference_percent`) in grams. |
| `price` | integer | Total price in the requested currency. |
| `type` | string | `"One way"` or `"Round trip"`. |
| `airline_logo` | string | Representative airline logo URL. |
| `departure_token` | string | Per-flight short token when emitted by Google. |
| `booking_token` | string | Opaque token identifying the booking page. |

***

### Example Output

```json
{
    "search_parameters": {
        "engine": "google_flights",
        "type": 2,
        "departure_id": "JFK",
        "arrival_id": "LAX",
        "outbound_date": "2026-06-15",
        "adults": 1,
        "currency": "USD",
        "gl": "us",
        "hl": "en"
    },
    "best_flights": [
        {
            "flights": [
                {
                    "departure_airport": {
                        "name": "John F. Kennedy International Airport",
                        "id": "JFK",
                        "time": "2026-06-15 08:29"
                    },
                    "arrival_airport": {
                        "name": "Los Angeles International Airport",
                        "id": "LAX",
                        "time": "2026-06-15 11:25"
                    },
                    "duration": 356,
                    "airplane": "Airbus A320",
                    "airline": "JetBlue",
                    "airline_logo": "https://www.gstatic.com/flights/airline_logos/70px/B6.png",
                    "travel_class": "Economy",
                    "flight_number": "B6 323",
                    "legroom": "32 inches",
                    "extensions": [
                        "Wi-Fi for a fee",
                        "In-seat power"
                    ],
                    "overnight": false
                }
            ],
            "layovers": [],
            "total_duration": 356,
            "carbon_emissions": {
                "this_flight": 405000,
                "typical_for_this_route": 316000,
                "difference_percent": 28
            },
            "price": 149,
            "type": "One way",
            "airline_logo": "https://www.gstatic.com/flights/airline_logos/70px/B6.png",
            "booking_token": "CjRIVVBMZHNBZEpBRDhBQmN1QndCRy0..."
        }
    ],
    "other_flights": [],
    "price_insights": {
        "lowest_price": 149,
        "price_level": "typical",
        "typical_price_range": [90, 205],
        "price_history": [
            [1771218000000, 169]
        ]
    },
    "airports": [
        {
            "departure": [
                {
                    "airport": {
                        "id": "JFK",
                        "name": "John F. Kennedy International Airport"
                    },
                    "city": "New York",
                    "country": "United States",
                    "country_code": "US",
                    "latitude": 40.6397,
                    "longitude": -73.7789
                }
            ],
            "arrival": [
                {
                    "airport": {
                        "id": "LAX",
                        "name": "Los Angeles International Airport"
                    },
                    "city": "Los Angeles",
                    "country": "United States",
                    "country_code": "US",
                    "latitude": 33.9425,
                    "longitude": -118.4081
                }
            ]
        }
    ]
}
```

***

### Sort Modes (`sort_by`)

| Value | Meaning |
|---|---|
| `1` (default) | Top — Google's default ranking |
| `2` | Price ascending |
| `3` | Departure time ascending |
| `4` | Arrival time ascending |
| `5` | Total duration ascending |
| `6` | Carbon emissions ascending |

***

### Stop Filters (`stops`)

| Value | Meaning |
|---|---|
| `0` (default) | Any number of stops |
| `1` | Nonstop only |
| `2` | At most 1 stop |
| `3` | At most 2 stops |

***

### Important Notes

- **Listing data only.** `booking_token` points to the upstream booking page but fare detail / baggage / seat map expansion is not currently exposed.
- **Dates must be today or in the future.** Past dates return an error.
- **Travel class changes the fares returned.** Business and first-class searches return their own cabin prices.
- **Sorting changes the result split.** With default `sort_by=1`, results split into `best_flights` and `other_flights`. With `sort_by=2` through `6`, ordered results arrive under `other_flights` and `best_flights` is empty.
- **Prices are integer units** in the requested currency; sub-unit precision is dropped.
- **Live prices drift.** Fares can change between requests; expect small variance on repeated calls.

***

### Error Handling

The actor fails with a descriptive message when:

| Condition | Actor Behavior |
|---|---|
| `departure_id` missing or empty | Actor fails with validation error. |
| `arrival_id` missing or empty | Actor fails with validation error. |
| `outbound_date` missing, malformed, or in the past | Actor fails with validation error. |
| `return_date` required but missing (round-trip) | Actor fails with validation error. |
| `return_date` before `outbound_date` | Actor fails with validation error. |
| `type=3` (multi-city) requested | Actor fails — not yet supported. |
| `include_airlines` and `exclude_airlines` both set | Actor fails — mutually exclusive. |
| Invalid `travel_class`, `stops`, or `sort_by` values | Actor fails with validation error. |
| API returns HTTP 4xx/5xx | Actor fails with HTTP status and response preview. |
| Network timeout or error | Actor fails with network error details. |
| Invalid JSON response | Actor fails with parse error message. |

***

# Actor input Schema

## `departure_id` (type: `string`):

Origin IATA airport code. Use comma-separated codes for multi-airport origin (e.g. JFK,LGA,EWR).

## `arrival_id` (type: `string`):

Destination IATA airport code. Use comma-separated codes for multi-airport destination.

## `outbound_date` (type: `string`):

Departure date in YYYY-MM-DD format. Must be today or a future date.

## `return_date` (type: `string`):

Return date in YYYY-MM-DD format. Required when type=1 (round-trip). Must be on or after outbound_date.

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

1 = round trip (requires return_date), 2 = one way. Auto-inferred from return_date if omitted.

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

Number of adult passengers (1–9).

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

Number of child passengers (0–9).

## `infants_in_seat` (type: `integer`):

Number of infants in seat (0–4).

## `infants_on_lap` (type: `integer`):

Number of infants on lap (0–4).

## `travel_class` (type: `string`):

Cabin class for the search.

## `stops` (type: `string`):

Maximum number of stops.

## `sort_by` (type: `string`):

Result sorting order.

## `include_airlines` (type: `string`):

Comma-separated IATA airline codes to include (e.g. DL,B6,AA). Mutually exclusive with exclude_airlines.

## `exclude_airlines` (type: `string`):

Comma-separated IATA airline codes to exclude. Mutually exclusive with include_airlines.

## `show_hidden` (type: `boolean`):

When true, appends itineraries hidden behind the 'View more flights' button to other_flights. Some hidden itineraries may omit price.

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

Language code (ISO 639-1). Controls the language of results.

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

Country code (ISO 3166-1 alpha-2). Controls regional pricing and results.

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

Currency code for prices (e.g. USD, EUR, GBP, JPY, TRY).

## Actor input object example

```json
{
  "departure_id": "JFK",
  "arrival_id": "LAX",
  "outbound_date": "2026-12-15",
  "adults": 1,
  "children": 0,
  "infants_in_seat": 0,
  "infants_on_lap": 0,
  "travel_class": "1",
  "stops": "0",
  "sort_by": "1",
  "show_hidden": false,
  "hl": "en",
  "gl": "us",
  "currency": "USD"
}
```

# Actor output Schema

## `flightResults` (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 = {
    "departure_id": "JFK",
    "arrival_id": "LAX",
    "outbound_date": "2026-12-15"
};

// Run the Actor and wait for it to finish
const run = await client.actor("ilborso/google-flights-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 = {
    "departure_id": "JFK",
    "arrival_id": "LAX",
    "outbound_date": "2026-12-15",
}

# Run the Actor and wait for it to finish
run = client.actor("ilborso/google-flights-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 '{
  "departure_id": "JFK",
  "arrival_id": "LAX",
  "outbound_date": "2026-12-15"
}' |
apify call ilborso/google-flights-api --silent --output-dataset

```

## MCP server setup

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