---
title: "Google Flights search"
method: GET
path: "/v1/google/flights/search"
tags: ["Google Flights"]
---

# Google Flights search

`GET /v1/google/flights/search`

Search Google Flights.

Returns ``best_flights`` (Google's top 4 picks) and ``other_flights``
(the rest of the SSR-rendered result set), plus ``price_insights``
when Google flags a typical-price range. Each offer carries a
``booking_url`` deep link (built from the ``tfs`` token) that pre-selects
that flight, and the response carries a ``search_url`` for the whole
search.

For round-trips, follow an outbound offer's ``departure_token`` back into
this endpoint to list the **return-leg** flights; each returned offer then
carries a fully-selected ``selection_token`` / ``booking_url`` for the
complete itinerary.

Note: Google Flights renders a "best picks" preview in SSR (~6-8
flights per direction for round-trips, 3-4 for one-way).

## Query parameters

- `departure_id` string, required — Departure IATA (e.g. `JFK`) or airport ID.
- `arrival_id` string, required — Arrival IATA (e.g. `LHR`) or airport ID.
- `outbound_date` string, required — Outbound date — `YYYY-MM-DD`.
- `return_date` string, nullable — Return date (`YYYY-MM-DD`) — required for `trip_type=round_trip`.
- `trip_type` 'one_way' | 'round_trip' | 'multi_city' — `round_trip` / `one_way` / `multi_city`.
- `adults` integer — Adult passengers.
- `children` integer — Children passengers.
- `infants_in_seat` integer
- `infants_on_lap` integer
- `travel_class` 'economy' | 'premium_economy' | 'business' | 'first' — Cabin class.
- `currency` string — ISO-4217 currency code.
- `gl` string — Country code.
- `hl` string — Language code.
- `stops` 'any' | 'nonstop' | 'one_stop' | 'two_stops' — Max stops filter — applied client-side.
- `max_price` integer, nullable — Max price filter — applied client-side.
- `sort_by` 'top' | 'price' — `top` (default) returns Google's ~6-8 'best' picks — fast. `price` returns the full price-sorted inventory (every carrier, the cheap long-layover fares) plus Google's own price floor / typical range / history. `price` is slower (a heavier render) and falls back to the 'top' set under load. Round-trip initial search only.
- `departure_token` string, nullable — A `departure_token` from a round-trip offer. When set, the search returns the **return-leg** flights for that selected outbound (pass the same `departure_id`/`arrival_id`/dates as the original search). Round-trip only.

## Response `200`

Successful Response

- GoogleFlightsResponse — Response for GET /api/v1/flights/search.
  - `best_flights` FlightOffer[]
    - `legs` FlightLeg[] — Flight segments. On a round-trip search these are the **outbound** segments only (Google Flights picks the return in a second step) — pass the offer's `departure_token` back to `/flights/search` to list the return-leg options.
      - `departure_airport` string, nullable — IATA code
      - `departure_airport_name` string, nullable
      - `departure_time` string, nullable — ISO-8601 local time of departure
      - `arrival_airport` string, nullable
      - `arrival_airport_name` string, nullable
      - `arrival_time` string, nullable
      - `duration_minutes` integer, nullable
      - `airline` string, nullable
      - `airline_logo` string, nullable
      - `flight_number` string, nullable
      - `aircraft` string, nullable
      - `travel_class` string, nullable
      - `legroom` string, nullable
      - `extensions` string[]
    - `layovers` FlightLayover[]
      - `duration_minutes` integer, nullable
      - `airport` string, nullable
      - `airport_name` string, nullable
      - `overnight` boolean
    - `total_duration_minutes` integer, nullable
    - `price` number, nullable — Price exactly as Google Flights displays it: the total for the **entire party** (all passengers), **including mandatory taxes and fees** (optional extras like bags/seats excluded). On a round-trip search this is the lowest complete round-trip total available with this outbound (paired with the cheapest compatible return); the `departure_token` follow-up returns the exact final total per return choice.
    - `currency` string, nullable
    - `price_type` 'base' | 'total', nullable — `total` — `price` covers the full itinerary (both legs of a round trip) for all travelers combined.
    - `booking_token` string, nullable
    - `booking_url` string, nullable — Deep link that pre-selects this exact flight on Google Flights. For one-way it opens the booking-options page (airline/OTA links); for round-trip it opens the return-flight selection for this outbound. Built from the `tfs` token, language-independent.
    - `selection_token` string, nullable — Opaque `tfs` token for this selection. Pass to `GET /flights/booking_options` to retrieve the provider booking list (works for one-way / fully-selected itineraries).
    - `departure_token` string, nullable — Round-trip outbound-selection token (same value as `selection_token`); pre-selects this outbound and advances to the return-flight picker. `None` for one-way searches.
    - `carbon_emissions_grams` integer, nullable
    - `carbon_emissions_diff_typical` integer, nullable — Difference vs typical emissions for this route, in grams
    - `airline_logo` string, nullable
    - `extensions` string[]
  - `other_flights` FlightOffer[]
    - `legs` FlightLeg[] — Flight segments. On a round-trip search these are the **outbound** segments only (Google Flights picks the return in a second step) — pass the offer's `departure_token` back to `/flights/search` to list the return-leg options.
      - `departure_airport` string, nullable — IATA code
      - `departure_airport_name` string, nullable
      - `departure_time` string, nullable — ISO-8601 local time of departure
      - `arrival_airport` string, nullable
      - `arrival_airport_name` string, nullable
      - `arrival_time` string, nullable
      - `duration_minutes` integer, nullable
      - `airline` string, nullable
      - `airline_logo` string, nullable
      - `flight_number` string, nullable
      - `aircraft` string, nullable
      - `travel_class` string, nullable
      - `legroom` string, nullable
      - `extensions` string[]
    - `layovers` FlightLayover[]
      - `duration_minutes` integer, nullable
      - `airport` string, nullable
      - `airport_name` string, nullable
      - `overnight` boolean
    - `total_duration_minutes` integer, nullable
    - `price` number, nullable — Price exactly as Google Flights displays it: the total for the **entire party** (all passengers), **including mandatory taxes and fees** (optional extras like bags/seats excluded). On a round-trip search this is the lowest complete round-trip total available with this outbound (paired with the cheapest compatible return); the `departure_token` follow-up returns the exact final total per return choice.
    - `currency` string, nullable
    - `price_type` 'base' | 'total', nullable — `total` — `price` covers the full itinerary (both legs of a round trip) for all travelers combined.
    - `booking_token` string, nullable
    - `booking_url` string, nullable — Deep link that pre-selects this exact flight on Google Flights. For one-way it opens the booking-options page (airline/OTA links); for round-trip it opens the return-flight selection for this outbound. Built from the `tfs` token, language-independent.
    - `selection_token` string, nullable — Opaque `tfs` token for this selection. Pass to `GET /flights/booking_options` to retrieve the provider booking list (works for one-way / fully-selected itineraries).
    - `departure_token` string, nullable — Round-trip outbound-selection token (same value as `selection_token`); pre-selects this outbound and advances to the return-flight picker. `None` for one-way searches.
    - `carbon_emissions_grams` integer, nullable
    - `carbon_emissions_diff_typical` integer, nullable — Difference vs typical emissions for this route, in grams
    - `airline_logo` string, nullable
    - `extensions` string[]
  - `price_insights` FlightPriceInsights — Typical price range insight for the searched route.
    - `lowest_price` number, nullable
    - `price_level` 'low' | 'typical' | 'high', nullable
    - `typical_price_range` number[], nullable — [min, max] typical price for this route
    - `price_history` array[], nullable — Historical price points as [[unix_timestamp, price], ...]
      - number[]
  - `airports` FlightAirport[]
    - `iata_code` string, required
    - `name` string, nullable
    - `city` string, nullable
    - `country` string, nullable
  - `departure_id` string, required
  - `arrival_id` string, required
  - `outbound_date` string, required
  - `return_date` string, nullable
  - `currency` string
  - `trip_type` 'one_way' | 'round_trip' | 'multi_city'
  - `search_url` string, nullable — Canonical Google Flights `tfs` URL for this search (in the requested language; market and prices follow `gl`/`currency`) — open to view and book the listed flights.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/scrapebadger/apis/scrapebadger-account-api.md) · [All operations](https://skmtc.net/scrapebadger/apis/scrapebadger-account-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scrapebadger/scrapebadger-account-api/revisions/4a1ef8777baf/schema)