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:

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

Round trip, two adults, business class, EUR:

{
    "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:

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

Include Hidden Itineraries **

{
  "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)

{
  "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

{
  "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

{
    "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.

---