# Google Flights search: `POST /v1/serp/google_flights`

Cost: 4 credits (4 (failed requests are free)). Docs: https://scrapercompany.com/docs/reference/google-flights

Every itinerary Google Flights offers, with per-segment detail.

Google's best and other flights, flight numbers, operating carrier,
aircraft, legroom, amenities, layovers, emissions, bags included, price
insights and a Google Flights link per itinerary. Round trips and
multi-city return the first leg's options with a `departure_token` for
`/v1/serp/google_flights_return`; complete itineraries carry a
`booking_token` for `/v1/serp/google_flights_booking`.

Request body (JSON):

- `departure` (string; required; min length 3, max length 3): IATA airport code (`JFK`) or IATA city code (`NYC`, `LON`, `PAR`, `TYO`...: every airport of that city). For several airports or a Google city id use `departure_id`.
- `arrival` (string; required; min length 3, max length 3): IATA airport code (`JFK`) or IATA city code (`NYC`, `LON`, `PAR`, `TYO`...: every airport of that city). For several airports or a Google city id use `arrival_id`.
- `departure_date` (string (date); required): Outbound flight date, `YYYY-MM-DD`.
- `return_date` (string (date) | null; optional): Return flight date for round-trip. Omit for one-way.
- `departure_id` (string | null; optional; min length 3, max length 200): SerpApi's `departure_id`: overrides `departure` with comma-separated IATA airport/city codes and/or Google city ids (`/m/02_286`), up to 7. `departure` is then only the label echoed back.
- `arrival_id` (string | null; optional; min length 3, max length 200): SerpApi's `arrival_id`: overrides `arrival` the same way, e.g. a city id from `/v1/serp/google_flights_location_search`.
- `multi_city` (array of object | null; optional; min items 1, max items 4): Makes the trip multi-city: the legs after the first (`departure` -> `arrival` on `departure_date`), 1-4 of them, in date order. The response lists options for the first leg; follow `departure_token` for each next leg. Not combinable with `return_date`.
  - `multi_city[].departure` (string; required; min length 3, max length 80): IATA airport code (`JFK`), IATA city code (`NYC`, `LON`, `PAR`: every airport of the city), a Google city id from `/v1/serp/google_flights_location_search` (`/m/02_286`), or up to 7 of these comma-separated (`JFK,EWR`).
  - `multi_city[].arrival` (string; required; min length 3, max length 80): IATA airport code (`JFK`), IATA city code (`NYC`, `LON`, `PAR`: every airport of the city), a Google city id from `/v1/serp/google_flights_location_search` (`/m/02_286`), or up to 7 of these comma-separated (`JFK,EWR`).
  - `multi_city[].date` (string (date); required): Departure date of this leg, `YYYY-MM-DD`.
  - `multi_city[].times` (string | null; optional; pattern ^\d{1,2},\d{1,2}(,\d{1,2},\d{1,2})?$): Hour window `from,to` for departure, optionally followed by `from,to` for arrival (0-23; `8,12` = leaves 08:00-12:59). SerpApi's format.
- `adults` (integer; optional; default 1; min 1, max 9): Number of adult passengers (12+ years old).
- `children` (integer; optional; default 0; min 0, max 8): Number of children (2-11 years old).
- `infants_in_seat` (integer; optional; default 0; min 0, max 4): Number of infants with seat (under 2 years old).
- `infants_on_lap` (integer; optional; default 0; min 0, max 4): Number of lap infants (under 2 years old); at most one per adult.
- `cabin_class` (string; optional; default economy; one of business, economy, first, premium_economy; pattern ^(economy|premium_economy|business|first)$): Cabin class: economy, premium_economy, business, first.
- `currency` (string; optional; default USD; one of AED, ARS, AUD, BRL, CAD, CHF, CLP, CNY, COP, CZK, DKK, EGP, EUR, GBP, HKD, HUF, IDR, ILS, INR, JPY, KRW, MXN, MYR, NOK, NZD, PEN, PHP, PLN, QAR, RON, SAR, SEK, SGD, THB, TRY, TWD, USD, VND, ZAR): ISO 4217 code for the returned prices. Major currencies include AED, AUD, BRL, CAD, CHF, CNY, EUR, GBP, HKD, INR, JPY, KRW, MXN, NZD, SGD, USD; all 39 supported codes are listed in the enum.
- `hl` (string; optional; default en): Language code for results.
- `gl` (string; optional; default us; one of ad, ae, af, ag, ai, al, am, ao, aq, ar, as, at, au, aw, ax, az, ba, bb, bd, be, bf, bg, bh, bi, bj, bl, bm, bn, bo, bq, br, bs, bt, bv, bw, by, bz, ca, cc, cd, cf, cg, ch, ci, ck, cl, cm, cn, co, cr, cu, cv, cw, cx, cy, cz, de, dj, dk, dm, do, dz, ec, ee, eg, eh, er, es, et, fi, fj, fk, fm, fo, fr, ga, gb, gd, ge, gf, gg, gh, gi, gl, gm, gn, gp, gq, gr, gs, gt, gu, gw, gy, hk, hm, hn, hr, ht, hu, id, ie, il, im, in, io, iq, ir, is, it, je, jm, jo, jp, ke, kg, kh, ki, km, kn, kp, kr, kw, ky, kz, la, lb, lc, li, lk, lr, ls, lt, lu, lv, ly, ma, mc, md, me, mf, mg, mh, mk, ml, mm, mn, mo, mp, mq, mr, ms, mt, mu, mv, mw, mx, my, mz, na, nc, ne, nf, ng, ni, nl, no, np, nr, nu, nz, om, pa, pe, pf, pg, ph, pk, pl, pm, pn, pr, ps, pt, pw, py, qa, re, ro, rs, ru, rw, sa, sb, sc, sd, se, sg, sh, si, sj, sk, sl, sm, sn, so, sr, ss, st, sv, sx, sy, sz, tc, td, tf, tg, th, tj, tk, tl, tm, tn, to, tr, tt, tv, tw, tz, ua, ug, uk, um, us, uy, uz, va, vc, ve, vg, vi, vn, vu, wf, ws, xk, ye, yt, za, zm, zw): Market/country code (two letters).
- `stops` (integer | null; optional; min 0, max 2): Maximum stops filter: 0=nonstop only, 1=max 1 stop, 2=max 2 stops. Omit for any number of stops.
- `include_airlines` (string | null; optional; pattern ^[A-Za-z0-9_]{2,13}(,[A-Za-z0-9_]{2,13}){0,19}$): Comma-separated IATA airline codes and/or alliances (`STAR_ALLIANCE`, `SKYTEAM`, `ONEWORLD`) to keep, e.g. `AC,UA`. Cannot be combined with `exclude_airlines`.
- `exclude_airlines` (string | null; optional; pattern ^[A-Za-z0-9_]{2,13}(,[A-Za-z0-9_]{2,13}){0,19}$): Comma-separated airline codes to drop. Google's rule: an itinerary also sold under a codeshare partner that is not excluded is kept.
- `max_price` (integer | null; optional; min 1, max 1000000): Only itineraries at or below this price, in `currency`.
- `max_duration` (integer | null; optional; min 30, max 5760): Maximum door-to-door travel time per leg, minutes.
- `outbound_times` (string | null; optional; pattern ^\d{1,2},\d{1,2}(,\d{1,2},\d{1,2})?$): Hour window `from,to` for departure, optionally followed by `from,to` for arrival (0-23; `8,12` = leaves 08:00-12:59). SerpApi's format. First leg.
- `return_times` (string | null; optional; pattern ^\d{1,2},\d{1,2}(,\d{1,2},\d{1,2})?$): Hour window `from,to` for departure, optionally followed by `from,to` for arrival (0-23; `8,12` = leaves 08:00-12:59). SerpApi's format. Return leg; needs `return_date`.
- `carry_on_bags` (integer; optional; default 0; min 0, max 1): Carry-on bags per passenger to include in the price (Google adds the airline's bag fees).
- `checked_bags` (integer; optional; default 0; min 0, max 2): Checked bags per passenger to include in the price.
- `exclude_basic_economy` (boolean; optional; default false): Hide basic-economy fares (Google's "Economy (exclude Basic)"; offered on US routes).
- `less_emissions` (boolean; optional; default false): Only flights with lower-than-typical emissions.
- `layover_duration` (string | null; optional; pattern ^\d{1,4},\d{1,4}$): Layover length window `min,max` in minutes, e.g. `60,240`.
- `connecting_airports` (string | null; optional; pattern ^[A-Za-z0-9]{3}(,[A-Za-z0-9]{3}){0,19}$): Only connect through these airports (comma-separated IATA codes).
- `exclude_connecting_airports` (string | null; optional; pattern ^[A-Za-z0-9]{3}(,[A-Za-z0-9]{3}){0,19}$): Never connect through these airports.
- `sort_by` (string; optional; default top_flights; one of arrival_time, departure_time, duration, emissions, price, top_flights; pattern ^(top_flights|price|departure_time|arrival_time|duration|emissions)$): Result order (SerpApi `sort_by` 1-6 in the same order): top_flights, price, departure_time, arrival_time, duration, emissions. With anything but top_flights Google returns no separate best group.

Response fields:

- `departure_airport` (string; required): Echo of the request's `departure`.
- `arrival_airport` (string; required): Echo of the request's `arrival`.
- `departure_date` (string (date); required): Date of the leg these options are for.
- `return_date` (string (date); optional): Present only for round trips.
- `currency` (string; required): The requested currency.
- `adults` (integer; required)
- `itineraries` (array of object; required): Options for the leg being chosen: Google's best flights first, then the others.
  - `itineraries[].legs` (array of object; required): The leg chosen in this call (one entry). Earlier legs are not repeated; `/v1/serp/google_flights_booking` returns every leg.
  - `itineraries[].price` (number | null; required): Google's displayed whole amount for the whole trip (every leg, all passengers), in `currency`. Google rounds up (527 where the exact fare is 526.19; see `price_exact`). When `priced_in` is set, the amount is in that currency instead.
  - `itineraries[].currency` (string; required): The requested currency.
  - `itineraries[].display_price` (string | null; required): `price` with its currency symbol, e.g. `$527`. Null when `price` is null or `priced_in` is set.
  - `itineraries[].booking_token` (string | null; required): Pass to `POST /v1/serp/google_flights_booking` for sellers, prices and booking links. Set only on complete itineraries (one-way options, and the options of a trip's last leg); null when `departure_token` is set. Compatibility: until 2026-09-30 this field held Google's raw price token on every itinerary; that value is now `price_token`.
  - `itineraries[].booking_url` (string | null; required): Google Flights booking page for the complete itinerary. Set together with `booking_token`.
  - `itineraries[].carbon_emissions_kg` (integer | null; required): CO2e estimate for this itinerary, kilograms (rounded). `carbon_emissions` has the same figure in grams.
  - `itineraries[].carbon_emissions_comparison` (string | null; required): e.g. `19% lower than typical` or `typical for this route`.
  - `itineraries[].trip_type` (string; required; one of one_way, round_trip, multi_city): `one_way`, `round_trip` or `multi_city`.
  - `itineraries[].total_stops` (integer; required): Stops across `legs`.
  - `itineraries[].is_direct` (boolean; required): `total_stops` is 0.
  - `itineraries[].departure_token` (string | null; required): Pass to `POST /v1/serp/google_flights_return` for the next leg's options after choosing this one. Set while legs remain to choose (round-trip outbound, multi-city legs before the last); null when `booking_token` is set. Self-contained: nothing else is needed with it.
  - `itineraries[].google_flights_url` (string | null; required): Google Flights page for this option: the search page with the earlier legs chosen, or the booking page once every leg is chosen.
  - `itineraries[].group` (string; required; one of best, other): `best` (Google's top flights) or `other`. Every option is `other` when `sort_by` is not `top_flights`.
  - `itineraries[].price_exact` (number | null; required): Price with minor units, from Google's price token (526.19 where `price` is 527). Null when the token has no amount or is in another currency.
  - `itineraries[].price_token` (string | null; required): Google's own opaque price token for this option, on every itinerary (returned as `booking_token` until 2026-09-30). Usable as an itinerary key; no endpoint takes it.
  - `itineraries[].priced_in` (string | null; required): Set only when Google priced this option in another currency than requested: that ISO 4217 code. `price` is then in this currency and `warnings` says so.
  - `itineraries[].carbon_emissions` (object | null; required): Null when Google gives no estimate.
  - `itineraries[].total_duration_minutes` (integer | null; required): Sum of the legs' door-to-door durations, minutes; null when one is unknown.
  - `itineraries[].carry_on_bags_included` (integer | null; required): Carry-on bags included in the fare, as Google states it; null when not stated.
  - `itineraries[].checked_bags_included` (integer | null; required): Checked bags included in the fare, as Google states it; null when not stated.
  - `itineraries[].airline_logo` (string | null; required): Logo URL of the main airline; null when several airlines share the itinerary.
- `elapsed_s` (number; required): Time Google took to answer, seconds.
- `cheapest_price` (number | null; required): Lowest `price` in `itineraries`; null when none is priced.
- `trip_type` (string; required; one of one_way, round_trip, multi_city): `one_way`, `round_trip` or `multi_city`.
- `leg_index` (integer; required): Which leg these options are for: 0 = first (outbound), 1 = return or second multi-city leg, and so on.
- `legs_total` (integer; required): Legs in the trip: 1 one-way, 2 round trip, 2-5 multi-city.
- `itinerary_count` (integer; required): Number of entries in `itineraries`.
- `best_count` (integer; required): How many `itineraries` have `group: best`.
- `price_insights` (object | null; optional): Null when Google gives none (some filtered searches). Omitted when `itineraries` is empty; that answer is not billed.
  - `price_insights.lowest_price` (number | null; required): Lowest price Google shows for this search, in `currency`.
  - `price_insights.price_level` (string | null; required; one of low, typical, high): Google's verdict on today's price: `low` (below its typical range), `typical` (inside it) or `high` (above it).
  - `price_insights.typical_price_range` (array of number | null; required; min items 2, max items 2): `[low, high]`: Google's typical price range for this trip.
  - `price_insights.price_history` (array of array of number; required): `[[unix_seconds, price], ...]`: Google's price history for this trip, about 60 days. Empty when Google gives none.
- `airlines_available` (array of object; required): Airlines and alliances Google offers as filters for this search; the codes work in `include_airlines`.
  - `airlines_available[].code` (string; required): IATA airline code, or `STAR_ALLIANCE` / `SKYTEAM` / `ONEWORLD`.
  - `airlines_available[].name` (string | null; required)
  - `airlines_available[].type` (string; required; one of alliance, airline)
- `google_flights_url` (string; required): Google Flights search page for this trip.
- `source` (string; required; one of rpc, html): `rpc` normally; `html` when the results came from Google's server-rendered page fallback, which holds only Google's first screen of results (about 8-10 itineraries).
- `warnings` (array of string; required): Notices about this answer, e.g. that Google priced some options in another currency (see each itinerary's `priced_in`). Empty when none.

Base URL: `https://api.scrapercompany.com`. Auth: send your key in the `x-api-key` header. A failed request (4xx or 5xx) or an empty result costs 0 credits.

- [Full API reference as one Markdown file](https://scrapercompany.com/llms-full.txt)
- [OpenAPI spec](https://scrapercompany.com/openapi.json)
