Question 1

How do I authenticate?

Accepted Answer

> 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.

Question 2

Do I need a Google account, API key or scraper of my own?

Accepted Answer

No. The API talks to Google Flights for you and returns structured JSON. You only
need your marketplace key.

Question 3

Is there a sandbox or test call I can make before writing code?

Accepted Answer

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.

Question 4

How fresh are the prices?

Accepted Answer

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.

Question 5

Where does the data come from?

Accepted Answer

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.

Question 6

Why do results differ slightly from what I see on google.com/travel/flights?

Accepted Answer

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.

Question 7

Which routes and airports are covered?

Accepted Answer

Anything Google Flights covers. Airport codes are resolved from a bundled dataset
of **6,000+ airports** exposed through `GET /v1/airports/search`.

Question 8

Can I use city or metro codes like `NYC` or `LON`?

Accepted Answer

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.

Question 9

Which currencies, languages and markets can I request?

Accepted Answer

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.

Question 10

Do you support round trips? Multi-city? Open-jaw?

Accepted Answer

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.

Question 11

Can I filter by nonstop, cabin class or passenger mix?

Accepted Answer

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`.

Question 12

Why is `price` sometimes `null`?

Accepted Answer

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.

Question 13

What do `priceLevel`, `co2Kg`, `selfTransfer` and `arrivalDayOffset` mean?

Accepted Answer

- `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.

Question 14

Are `departureTime` / `arrivalTime` local times?

Accepted Answer

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.

Question 15

Does the response include flight numbers, fare rules, baggage or booking links?

Accepted Answer

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.

Question 16

Why does `price-history` come back with an empty `series`?

Accepted Answer

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.

Question 17

How fast is each endpoint?

Accepted Answer

`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.

Question 18

Do airport lookups count against my quota?

Accepted Answer

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.

Question 19

What do the error codes mean, and which should I retry?

Accepted Answer

| 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": ... }`.

Question 20

I keep getting `502 upstream_error` — what should I do?

Accepted Answer

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.

Question 21

Is this API affiliated with Google?

Accepted Answer

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.

Question 22

How do I report a wrong result or request a feature?

Accepted Answer

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.

Google Flights

Frequently Asked Questions