> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapebadger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Flights Search

> Search Google Flights for one-way, round-trip, or multi-city itineraries with prices, emissions, and price insights.

## Prices

`price` is the price exactly as Google Flights displays it: the **total for the
entire party** (all passengers combined), **including mandatory taxes and
fees**. Optional extras such as checked bags or seat selection are not
included. `price_type` is always `total`.

## Round trips: the two-step flow

Google Flights selects a round trip in two steps — first the outbound, then the
return — and this API mirrors that:

1. **Search** with `trip_type=round_trip`, `outbound_date`, and `return_date`.
   Each offer's `legs` contain the **outbound segments only**, and its `price`
   is the lowest complete round-trip total available with that outbound (Google
   pairs it with the cheapest compatible return).
2. **Pick the return**: call this endpoint again with the same parameters plus
   the chosen offer's `departure_token`. The response lists the return-leg
   options; each offer's `price` is the exact final round-trip total for that
   outbound + return pairing, and its `booking_url` opens the Google Flights
   booking page for the fully selected itinerary. Use its `selection_token`
   with [Booking Options](/api-reference/google/google-flights/flights-booking-options)
   to list per-provider prices.

Each call is billed as a regular Flights search.

For **one-way** searches the offer is already fully selected: `booking_url`
opens the booking page directly and `departure_token` is `null`.


## OpenAPI

````yaml GET /v1/google/flights/search
openapi: 3.1.0
info:
  title: ScrapeBadger Google Scraper
  description: >-
    Dedicated API for scraping Google products (SERP, Maps, News, Hotels,
    Trends, Jobs, Shopping, Patents, Scholar, Autocomplete, Images, Videos,
    Finance, AI Mode, Lens, Products).
  version: 1.0.0
servers:
  - url: https://scrapebadger.com
    description: Production
security:
  - apiKeyAuth: []
paths:
  /v1/google/flights/search:
    get:
      tags:
        - Google Flights
      summary: Google Flights search
      description: >-
        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).
      operationId: googleFlightsSearch
      parameters:
        - name: departure_id
          in: query
          required: true
          schema:
            type: string
            description: Departure IATA (e.g. `JFK`) or airport ID.
            title: Departure Id
          description: Departure IATA (e.g. `JFK`) or airport ID.
        - name: arrival_id
          in: query
          required: true
          schema:
            type: string
            description: Arrival IATA (e.g. `LHR`) or airport ID.
            title: Arrival Id
          description: Arrival IATA (e.g. `LHR`) or airport ID.
        - name: outbound_date
          in: query
          required: true
          schema:
            type: string
            description: Outbound date — `YYYY-MM-DD`.
            title: Outbound Date
          description: Outbound date — `YYYY-MM-DD`.
        - name: return_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Return date (`YYYY-MM-DD`) — required for `trip_type=round_trip`.
            title: Return Date
          description: Return date (`YYYY-MM-DD`) — required for `trip_type=round_trip`.
        - name: trip_type
          in: query
          required: false
          schema:
            enum:
              - one_way
              - round_trip
              - multi_city
            type: string
            description: '`round_trip` / `one_way` / `multi_city`.'
            default: round_trip
            title: Trip Type
          description: '`round_trip` / `one_way` / `multi_city`.'
        - name: adults
          in: query
          required: false
          schema:
            type: integer
            maximum: 9
            minimum: 1
            description: Adult passengers.
            default: 1
            title: Adults
          description: Adult passengers.
        - name: children
          in: query
          required: false
          schema:
            type: integer
            maximum: 8
            minimum: 0
            description: Children passengers.
            default: 0
            title: Children
          description: Children passengers.
        - name: infants_in_seat
          in: query
          required: false
          schema:
            type: integer
            maximum: 4
            minimum: 0
            default: 0
            title: Infants In Seat
        - name: infants_on_lap
          in: query
          required: false
          schema:
            type: integer
            maximum: 4
            minimum: 0
            default: 0
            title: Infants On Lap
        - name: travel_class
          in: query
          required: false
          schema:
            enum:
              - economy
              - premium_economy
              - business
              - first
            type: string
            description: Cabin class.
            default: economy
            title: Travel Class
          description: Cabin class.
        - name: currency
          in: query
          required: false
          schema:
            type: string
            description: ISO-4217 currency code.
            default: USD
            title: Currency
          description: ISO-4217 currency code.
        - name: gl
          in: query
          required: false
          schema:
            type: string
            description: Country code.
            default: us
            title: Gl
          description: Country code.
        - name: hl
          in: query
          required: false
          schema:
            type: string
            description: Language code.
            default: en
            title: Hl
          description: Language code.
        - name: stops
          in: query
          required: false
          schema:
            enum:
              - any
              - nonstop
              - one_stop
              - two_stops
            type: string
            description: Max stops filter — applied client-side.
            default: any
            title: Stops
          description: Max stops filter — applied client-side.
        - name: max_price
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 1
              - type: 'null'
            description: Max price filter — applied client-side.
            title: Max Price
          description: Max price filter — applied client-side.
        - name: departure_token
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              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.
            title: Departure Token
          description: >-
            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.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleFlightsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    GoogleFlightsResponse:
      properties:
        best_flights:
          items:
            $ref: '#/components/schemas/FlightOffer'
          type: array
          title: Best Flights
        other_flights:
          items:
            $ref: '#/components/schemas/FlightOffer'
          type: array
          title: Other Flights
        price_insights:
          anyOf:
            - $ref: '#/components/schemas/FlightPriceInsights'
            - type: 'null'
        airports:
          items:
            $ref: '#/components/schemas/FlightAirport'
          type: array
          title: Airports
        departure_id:
          type: string
          title: Departure Id
        arrival_id:
          type: string
          title: Arrival Id
        outbound_date:
          type: string
          title: Outbound Date
        return_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Return Date
        currency:
          type: string
          title: Currency
          default: USD
        trip_type:
          type: string
          enum:
            - one_way
            - round_trip
            - multi_city
          title: Trip Type
          default: round_trip
        search_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Search Url
          description: >-
            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.
      type: object
      required:
        - departure_id
        - arrival_id
        - outbound_date
      title: GoogleFlightsResponse
      description: Response for GET /api/v1/flights/search.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    FlightOffer:
      properties:
        legs:
          items:
            $ref: '#/components/schemas/FlightLeg'
          type: array
          title: Legs
          description: >-
            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.
        layovers:
          items:
            $ref: '#/components/schemas/FlightLayover'
          type: array
          title: Layovers
        total_duration_minutes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Duration Minutes
        price:
          anyOf:
            - type: number
            - type: 'null'
          title: Price
          description: >-
            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:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency
        price_type:
          anyOf:
            - type: string
              enum:
                - base
                - total
            - type: 'null'
          title: Price Type
          description: >-
            `total` — `price` covers the full itinerary (both legs of a round
            trip) for all travelers combined.
        booking_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Booking Token
        booking_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Booking Url
          description: >-
            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:
          anyOf:
            - type: string
            - type: 'null'
          title: Selection Token
          description: >-
            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:
          anyOf:
            - type: string
            - type: 'null'
          title: Departure Token
          description: >-
            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:
          anyOf:
            - type: integer
            - type: 'null'
          title: Carbon Emissions Grams
        carbon_emissions_diff_typical:
          anyOf:
            - type: integer
            - type: 'null'
          title: Carbon Emissions Diff Typical
          description: Difference vs typical emissions for this route, in grams
        airline_logo:
          anyOf:
            - type: string
            - type: 'null'
          title: Airline Logo
        extensions:
          items:
            type: string
          type: array
          title: Extensions
      type: object
      title: FlightOffer
      description: A single end-to-end flight itinerary that appears in the results.
    FlightPriceInsights:
      properties:
        lowest_price:
          anyOf:
            - type: number
            - type: 'null'
          title: Lowest Price
        price_level:
          anyOf:
            - type: string
              enum:
                - low
                - typical
                - high
            - type: 'null'
          title: Price Level
        typical_price_range:
          anyOf:
            - items:
                type: number
              type: array
            - type: 'null'
          title: Typical Price Range
          description: '[min, max] typical price for this route'
        price_history:
          anyOf:
            - items:
                items:
                  type: number
                type: array
              type: array
            - type: 'null'
          title: Price History
          description: Historical price points as [[unix_timestamp, price], ...]
      type: object
      title: FlightPriceInsights
      description: Typical price range insight for the searched route.
    FlightAirport:
      properties:
        iata_code:
          type: string
          title: Iata Code
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
      type: object
      required:
        - iata_code
      title: FlightAirport
      description: Airport metadata referenced in a search result.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    FlightLeg:
      properties:
        departure_airport:
          anyOf:
            - type: string
            - type: 'null'
          title: Departure Airport
          description: IATA code
        departure_airport_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Departure Airport Name
        departure_time:
          anyOf:
            - type: string
            - type: 'null'
          title: Departure Time
          description: ISO-8601 local time of departure
        arrival_airport:
          anyOf:
            - type: string
            - type: 'null'
          title: Arrival Airport
        arrival_airport_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Arrival Airport Name
        arrival_time:
          anyOf:
            - type: string
            - type: 'null'
          title: Arrival Time
        duration_minutes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Duration Minutes
        airline:
          anyOf:
            - type: string
            - type: 'null'
          title: Airline
        airline_logo:
          anyOf:
            - type: string
            - type: 'null'
          title: Airline Logo
        flight_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Flight Number
        aircraft:
          anyOf:
            - type: string
            - type: 'null'
          title: Aircraft
        travel_class:
          anyOf:
            - type: string
            - type: 'null'
          title: Travel Class
        legroom:
          anyOf:
            - type: string
            - type: 'null'
          title: Legroom
        extensions:
          items:
            type: string
          type: array
          title: Extensions
      type: object
      title: FlightLeg
      description: One segment of a flight itinerary (e.g. SFO → LHR on a connection).
    FlightLayover:
      properties:
        duration_minutes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Duration Minutes
        airport:
          anyOf:
            - type: string
            - type: 'null'
          title: Airport
        airport_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Airport Name
        overnight:
          type: boolean
          title: Overnight
          default: false
      type: object
      title: FlightLayover
      description: A layover between two legs in a multi-segment itinerary.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````