Endpoints
Flights 3
System 1
Airports 1
openapi.json 1
What is the Google Flights API?
Real-time flight search powered by Google Flights — one-way & round-trip fares, price calendar, and airport autocomplete.
Google Flights API is available on the JoJ API marketplace. Subscribe with a single JoJ API key, call it through one gateway, and pay from one wallet — no separate account or contract with the provider.
Google Flights API endpoints
- GET
/v1/flights/calendar/v1/flights/calendar
Cheapest fare per departure date across a range (max 30 days). For round trips, supply `tripLengthDays`. Note: this performs multiple upstream lookups, so it is slower than a single search.
- GET
/v1/flights/price-history/v1/flights/price-history
Historical lowest prices observed for a route/date by this API over time. Requires Postgres persistence to be enabled; returns an empty series otherwise.
- GET
/v1/flights/search/v1/flights/search
Returns live itineraries from Google Flights for a one-way or round-trip route. Results are cached server-side; pass `refresh=true` to force a live fetch.
- GET
/health/health
Check service health
- GET
/v1/airports/search/v1/airports/search
Search airports by IATA code, city or name. Backed by a bundled dataset — fast and free (does not count against upstream rate limits).
- GET
/openapi.json/openapi.json
Service OpenAPI Spec
Frequently asked questions about Google Flights API
How do I authenticate?
> Create a key in your workspace and send it on every request: > ``` > X-JoJAPI-Key: jk_your_key > ``` > One key works across every API you have subscribed to; scope it to just this > API if you prefer. Usage comes back on each response in the > `X-Jojapi-*-Used` headers. There are no other tokens, no OAuth flow and no session to keep alive.
Do I need a Google account, API key or scraper of my own?
No. The API talks to Google Flights for you and returns structured JSON. You only need your marketplace key.
Is there a sandbox or test call I can make before writing code?
Yes — use the marketplace playground. The cheapest call to try is `GET /v1/airports/search?q=London`: it answers instantly from a bundled dataset and never depends on upstream availability.
How fresh are the prices?
Live at request time. Identical searches made shortly after one another may be served from a short-lived cache (up to an hour) — check the `source` field: `live` means it was just fetched, `cache` means it was reused. Pass `refresh=true` to force a live fetch and bypass the cache.
Where does the data come from?
Public Google Flights results, parsed into a stable JSON shape. Prices, airlines, durations, stops and CO₂ estimates are the ones Google displays for that route, market and currency at that moment.
Why do results differ slightly from what I see on google.com/travel/flights?
Three usual reasons: (1) you are comparing different markets — Google prices by country/currency, so pass the `currency` and `country` you actually want; (2) you hit the cache — add `refresh=true`; (3) fares genuinely move minute to minute. Always treat prices as indicative and confirm on the airline or booking site.
Which routes and airports are covered?
Anything Google Flights covers. Airport codes are resolved from a bundled dataset of **6,000+ airports** exposed through `GET /v1/airports/search`.
Can I use city or metro codes like `NYC` or `LON`?
No — `from` and `to` take a specific **airport** IATA code (`JFK`, `EWR`, `LHR`, `LGW`, …). Metro codes are not supported and return `400 bad_request`. Call `GET /v1/airports/search?q=New York` first and let the user pick, or map city → airport on your side.
Which currencies, languages and markets can I request?
Any ISO 4217 `currency`, BCP-47 `locale` and ISO 3166-1 `country`. Defaults are `USD` / `en-US` / `US`. `country` is the market Google prices for, which is what actually moves the number — set it together with `currency` for a coherent quote.
Do you support round trips? Multi-city? Open-jaw?
Round trips: yes — add `returnDate` to `GET /v1/flights/search` and the search becomes round-trip, with prices for the complete itinerary. Multi-city and open-jaw itineraries are not supported today.
Can I filter by nonstop, cabin class or passenger mix?
Yes: `stops` (`any`, `0` for nonstop, `1`, `2`), `cabinClass` (`economy`, `premium-economy`, `business`, `first`) and the full passenger mix — `adults` (1–9), `children`, `infantsInSeat`, `infantsOnLap`.
Why is `price` sometimes `null`?
Google occasionally displays an itinerary without a fare (typically sold-out or fareless rows). Rather than invent a number, the field comes back `null` and the rest of the itinerary — airlines, times, duration, stops — is still returned. `lowestPrice` only considers itineraries that do have a price.
What do `priceLevel`, `co2Kg`, `selfTransfer` and `arrivalDayOffset` mean?
- `priceLevel` — Google's own read on the fare: `low`, `typical`, `high`, or `null` when it has no opinion. Handy for a "good deal" badge. - `co2Kg` — estimated CO₂ in kilograms, when Google shows it; `null` otherwise. - `selfTransfer` — `true` when the itinerary combines separate tickets, so the traveller re-checks bags and bears the risk of a missed connection. - `arrivalDayOffset` — `0` means same-day arrival, `1` next day, `2` two days later. Use it instead of comparing the time strings.
Are `departureTime` / `arrivalTime` local times?
Yes — local to their own airport, formatted the way Google displays them (`7:35 PM`). For overnight flights pair `arrivalTime` with `arrivalDayOffset`. `durationMinutes` is the total travel time and is timezone-safe.
Does the response include flight numbers, fare rules, baggage or booking links?
No. Each itinerary carries operating airlines, price and currency, departure and arrival times and airports, duration, stop count and stop airports, CO₂ and price level. Booking happens on the airline or an OTA — this API is for search, comparison and price monitoring, not ticketing.
Why does `price-history` come back with an empty `series`?
History accumulates from live searches: a route/date that has not been searched before has nothing to report yet. Search the route first, keep querying it over time, and the series fills in.
How fast is each endpoint?
`airports/search` answers in milliseconds (local dataset). A cached `flights/search` is near-instant; a live one takes a few seconds, since it fetches and parses a real results page. `flights/calendar` is the slowest by design — it queries **one day at a time**, up to a 30-day range — so keep the range tight when latency matters.
Do airport lookups count against my quota?
They are billed like any other HTTP call by the marketplace, but they never touch Google, so they are instant and never fail with `502`. If you autocomplete on every keystroke, debounce the input or cache codes client-side.
What do the error codes mean, and which should I retry?
| Status | `error` | Meaning | Retry? | |:------:|---------|---------|--------| | `400` | `bad_request` | Invalid parameters or an unknown IATA code | No — fix the request | | `403` | `forbidden` | Missing or invalid subscription/key | No — check your key | | `429` | `rate_limited` | Plan quota exceeded | Yes, after backing off or upgrading | | `502` | `upstream_error` | Temporary problem reaching Google Flights | Yes, with exponential backoff | Every error uses the same envelope: `{ "error": "...", "message": "...", "statusCode": ... }`.
I keep getting `502 upstream_error` — what should I do?
It means Google throttled or blocked that particular fetch; it is transient. Wait a few seconds and retry with exponential backoff. If it persists for a specific route, report it (see below) — a markup change on Google's side is possible and gets fixed on our end.
Is this API affiliated with Google?
No. This API is independent and is not affiliated with, endorsed by, or sponsored by Google. "Google Flights" is a trademark of Google LLC. Prices are indicative and can change at any time — always confirm on the airline or booking site before purchase.
How do I report a wrong result or request a feature?
Use the support/contact channel on this API's listing. Include the exact request (route, dates, `currency`/`country`, all parameters), the timestamp, and what you expected versus what you got. That is usually enough to reproduce it immediately.