Google Flights

Structured, fully-priced flight offers with per-segment detail for any route and date — priced by Google Flights, a metasearch aggregator across airlines and sellers.

Base URL: https://api.scrapeguys.com · Auth: X-API-Key: fsk_… with the google_flights scope · See the Overview.

Submit a search

Omit return_date for a one-way search; include it for a round trip.

Metro area codes

A fixed set of metropolitan area codes is accepted alongside airport codes and expanded to every airport in that metro, searched together as one group — NYC covers JFK, LGA and EWR in a single search rather than just one of them.

Poll for results

Every search is an asynchronous job: the submit call answers 202 with a job_id and does no scraping itself. Poll every 1–2 seconds until status is completed or failed (it moves pending → processing → one of those). The poll body is the full job record — keyed id (not job_id) — echoing your search parameters alongside status, result, error_message, error_category and timing fields. While the job is pending or processing, result is null.

Every job also echoes source, platform and leg — which stage of the funnel it ran: search, fare_families, review, farelock, checkout, return_options or booking_options. A /scrape/ or /batch/ job is search; each expansion endpoint stamps its own, so the jobs of one chain can be told apart without reading result — including ones that failed before producing one. Rows that predate the field may read unknown; nothing writes it now.

Job record

An unknown job ID — or one that belongs to another client, or has aged out of retention — is 404 {"error": "Job not found."}.

Response schema

The result object holds flights[], search_context, search_metadata, and optionally calendar / per_leg_fares / cheapest_tab. Each flight carries a segments[] array.

Key fields

Batch scraping

Search up to 20 routes that share dates/region in one call.

Batch-level (shared) fields: departure_date, return_date, region, currency, include_calendar, calendar_days, calendar_days_before, per_leg_fares, include_cheapest, source (the MakeMyTrip-only include_price_lock and the MakeMyTrip/Paytm platform are also batch-level — see the MakeMyTrip guide). Per-route fields: origin, destination, adults, children, infants_in_seat, infants_on_lap, cabin_class, max_stops — dates, region, currency and source cannot vary per route. Each field has the same range and defaults as on a single search; a batch holds 1–20 routes (otherwise 400), and is validated as a whole before any job is created.

/batch/results/ returns the same job records as GET /scrape/{job_id}/, but with no ordering guarantee — match on id. It never errors on an individual ID: malformed IDs, IDs that belong to another client and jobs from a source your key is not scoped for are simply left out, so results can be shorter than job_ids. An empty list, more than 20 IDs, or no valid ID at all is 400 {"error": …}. Poll a job directly to get an explicit 404 or 403.

Round-trip expansion

On a round-trip search, each departing flight is priced as a round-trip total. To see the return options for a chosen outbound, submit an expansion job referencing the completed parent job and the outbound's index.

Guards: 404 if the parent job isn't yours; 400 if the parent job isn't completed, isn't a Google Flights round trip, outbound_index is out of range, or the chosen flight has no segments. Your key needs the google_flights scope (403 otherwise — checked before the parent is looked up). The expansion job repeats the parent's passengers, cabin, stops, region and currency. Expansion jobs never include calendar or per_leg_fares. Google Flights only — MakeMyTrip prices round trips differently, and not always the same way twice: two independently-selectable legs on domestic routes, one combined-fare card on international ones; see the MakeMyTrip Flights guide.

Booking options

Resolve a chosen flight to its actual sellers — airlines and OTAs with per-seller prices, booking links and baggage info. Submit an expansion job referencing a completed parent job and the flight's index.

• resolve_deep_links: true follows each seller's redirect to its real site URL into deep_link (slower; null on failure).
• Works on one-way jobs and return-expansion jobs. A round-trip /scrape/ job returns 400 — pick an outbound via /scrape/return/ first, then book from that job.
• Other 400 guards: parent not completed, parent not a Google Flights job, index out of range, or the chosen flight has no booking token/segments. An unknown parent is 404.
• flight_index counts into result.flights for a one-way parent and into result.return_options for a return-expansion parent.
• search_metadata.marketplace_attested signals whether the seller list is trustworthy; when false, some sellers may be missing. When true, also check marketplace_partial — attestation alone doesn't guarantee the list is complete.
• search_metadata.marketplace_partial — true when the server has evidence the returned seller list is short of what Google serves for this fare, so resubmitting the booking job may return more sellers. Always false when marketplace_attested is false (that case is already covered above). A resubmitted job repeats the whole lookup and is billed again, so branch on marketplace_attested / marketplace_partial rather than retrying blind.
• search_metadata.marketplace_readings — how many marketplace readings were combined to build the seller list (0 means the job failed before reading any). Normally 1 on an unattested job and 3 on an attested one; higher (up to ~8) when a thin reading needs extra re-reads to fill out. A thin first reading is automatically re-read from fresh exits before the job answers, so seller lists come back fuller — at the cost of longer booking jobs.
• legroom is the seat pitch as Google worded it, e.g. "32 in" — but the unit isn't pinned by the request. The same fare has been served as both "71 cm" and "28 in". Parse the unit before reading the number; don't assume inches.

Google Flights only — MakeMyTrip has no booking-options expansion; its own funnel is fare families and review, documented on the MakeMyTrip FlightsCleartrip Flights guide.

Calendar & per-leg fares

Calendar pricing — set include_calendar: true to get a date-grid summary: window_start/end, basis (always "one_way"), priced_days, cheapest, most_expensive, median, cheapest_dates, and a per-day days[] array of { date, return_date, price, booking_token } (price is null on days Google couldn't price). The window runs from today (or calendar_days_before before departure, if set — never earlier than today) through calendar_days after departure, and is capped at 180 days — an over-long window is trimmed from the front, keeping the dates nearest departure. Prices are one-way even on round trips. A calendar failure never fails the job — it surfaces as search_metadata.calendar_error with calendar: null.

Per-leg fares — set per_leg_fares: true on a round trip to compare booking the round trip vs. two one-ways: currency, outbound_one_way, return_one_way, two_one_ways_total, round_trip_total, round_trip_saving, round_trip_saving_pct, cheaper_as ("round_trip", "two_one_ways", or "either" when within 1%). If any leg couldn't be priced the object is null and the reason appears as search_metadata.per_leg_fares_error.

Both are Google Flights only — MakeMyTrip rejects include_calendar and per_leg_fares with 400 rather than accepting and ignoring them.

Attested Best readings

Not a request option — this is a server-side quality safeguard for the main flights[] results, and it's off by default. On some routes Google withholds entire itineraries — including the cheapest multi-airline connections — from a plain, unverified request, and returns them only to a caller it can verify. When the safeguard is enabled operator-side, the server spends a second, verified request on eligible searches and, if that reading is genuinely fuller or cheaper, serves it as flights[] in place of the plain one. There is nothing to set per request — you always get whichever reading the server judged best.

Google Flights only. Independent of the Cheapest tab below — that's a separate, opt-in side channel returned in cheapest_tab; this instead replaces the main flights[] in place and needs no request flag.

Cheapest tab

Set include_cheapest: true on /scrape/ (or on /batch/) to also get Google's Cheapest tab: the same itineraries priced at the best seller's fare rather than the headline one. Results land in result.cheapest_tab, in the same shape as result.flights — match entries between the two on flight_numbers.

Best-effort, and often returns nothing. cheapest_tab is null, or present with no cheaper prices, whenever the route genuinely has no cheaper seller right now, this is the first search of that route/date/passenger combination (no attestation exists yet — one is minted in the background; try again shortly), or Google served a suppressed reading despite a valid attestation. A job never fails because of the Cheapest tab — the Best-tab flights are unaffected either way.

Google Flights only — accepted but silently a no-op on a MakeMyTrip job. On /batch/, remember it's per-route: ten routes means ten Cheapest requests and, on cold routes, ten serialised browser mints — a large batch will mostly come back without Cheapest data.

Errors, limits & billing

These rules are shared by every /api/v1/flight-scraper/ endpoint, Google Flights and MakeMyTrip alike. Keys, rate limits and quotas are described in the Overview.

Keys start with fsk_ and are sent as X-API-Key. A hotel-API key (gsk_…) does not authenticate here. A scope is checked before the request uses any of your rate limit, so a 403 costs nothing.

What is billed

• One request unit per job you submit: a search, each route in a batch, and each expansion (return, booking, and the MakeMyTrip expansions). Optional add-ons — calendar, per-leg fares, Cheapest tab, price lock, deep-link resolution — do not change the unit count, only the work behind it.
• Usage is recorded when a job finishes, as a success or a failure — a failed job is billed like a completed one. Your daily and monthly quotas are checked against what has been recorded so far, so jobs still running are not yet counted.
• The per-minute rate limit is checked when you submit. Expansion requests are rate-checked before they are validated, so a refused expansion (400/404) still uses a slot of the per-minute allowance; a refused search or batch does not.
• Polling, /batch/results/ and GET /usage/ are never counted. Quotas are pooled per client across both sources. GET /api/v1/flight-scraper/usage/ reports your limits, billing period and daily counts.

Next: MakeMyTrip Flights →