Google Flights MCP, CLI and Python Library
fli (TypeScript)
A 1:1 TypeScript / JavaScript port of the Python fli library.
Programmatic access to Google Flights data via direct API interaction (no scraping). The API surface mirrors the Python package — same models, same filter encoding, same wire-format decoders — and, since Google gated its RPC endpoints, the same search-page transport.
Install
npm i fli-js # or: pnpm add fli-js / yarn add fli-js / bun add fli-js
Quick start
import {
Airport,
FlightSearchFilters,
FlightSegment,
MaxStops,
PassengerInfo,
SearchFlights,
SeatType,
SortBy,
} from "fli-js";
const filters = new FlightSearchFilters({
passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
flight_segments: [
new FlightSegment({
departure_airport: [[[Airport.JFK, 0]]],
arrival_airport: [[[Airport.LAX, 0]]],
travel_date: "2026-12-25",
}),
],
seat_type: SeatType.ECONOMY,
stops: MaxStops.NON_STOP,
sort_by: SortBy.CHEAPEST,
});
const results = await new SearchFlights().search(filters, { currency: "USD" });
console.log(results);
Date-range search
import { Airport, DateSearchFilters, FlightSegment, SearchDates } from "fli-js";
const filters = new DateSearchFilters({
passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
flight_segments: [
new FlightSegment({
departure_airport: [[[Airport.JFK, 0]]],
arrival_airport: [[[Airport.LAX, 0]]],
travel_date: "2026-12-01",
}),
],
from_date: "2026-12-01",
to_date: "2026-12-31",
});
const dates = await new SearchDates().search(filters);
Booking links
Turn search results into clickable Google Flights links — no extra network call, fully deterministic.
import { googleFlightsUrl, SearchFlights } from "fli-js";
const search = new SearchFlights();
const results = await search.search(filters, { currency: "USD" });
// Per-flight deep link: opens the specific itinerary's booking page
// (vendor fares + "Continue" CTA) via a `tfs` protobuf token.
const first = results?.[0];
if (first) {
console.log(search.buildFlightBookingUrl(first, { currency: "USD" }));
// https://www.google.com/travel/flights/booking?tfs=…&curr=USD
}
// Search-level deep link: route + dates pre-filled (handy for a date result
// or a quick "view on Google Flights" link).
console.log(googleFlightsUrl("JFK", "LHR", "2026-12-25", null, { currency: "USD" }));
// https://www.google.com/travel/flights?q=Flights%20from%20JFK%20to%20LHR%20on%202026-12-25&curr=USD
buildFlightBookingUrl accepts a single FlightResult (one-way) or an array
of them (round-trip / multi-city). It never throws — on malformed input it
falls back to the generic Google Flights URL.
Search transport
Searches are served by Google's public search page rather than the
FlightsFrontendService RPC. Since 2026-08 GetShoppingResults and
GetCalendarGraph require an x-goog-batchexecute-bgr header that only the
page's own JavaScript can produce, so a plain HTTP client gets HTTP 200 with no
payload. fli-js issues GET https://www.google.com/travel/flights?tfs=<protobuf>
instead and reads the results out of the page's inline AF_initDataCallback
blob keyed ds:1.
What that means in practice:
- Three filters are not supported.
emissions,bagsandexclude_basic_economyhave notfsfield and cannot be reconstructed from the decoded rows, so they are dropped with a warning. Stops, cabin, passengers, alliances and layover bounds ride in the request; airline include/exclude, price cap, max duration and departure windows are applied to the results after fetching, andsort_byorders them afterwards (TOP_FLIGHTS/BESTkeep Google's own ranking). - Multi-city throws
SearchUnsupportedError. Google loads those results client-side through the gated RPC, so the page carries no rows to read. Search each leg separately. getBookingOptionsis unavailable. It callsGetBookingResults, which is gated the same way, and currently throwsSearchRejectedError. The per-flighttfsbooking deep links (buildFlightBookingUrl) are built offline and still work.- Fewer rows per search. Expect roughly 20–45 itineraries, fewer than the old RPC returned — and a client-side filter cannot back-fill the list the way Google's server-side one did.
- Children and infants thin the results — sometimes to nothing. Google
prices those parties client-side, so the page inlines fewer itineraries for
them, and in premium cabins often none (measured 2026-09: JFK→LHR economy
23 rows for one adult, 16 with an infant; SFO→NRT business 9 rows for one
or two adults, 0 with a child). Extra adults cost nothing. An empty result
for such a search does not mean the route has no flights — and neither
does it mean this is why:
search()only warns when the fetched page itself came back with zero rows, not when the caller's own airline/price/ duration/window filter removed rows Google did return. An adults-only search shows the schedule. - Date searches cost one page fetch per date. The page has no calendar
grid, so a range is priced date by date; one
SearchDates.searchcovers at most 93 dates (MAX_DATES_PER_SEARCH) and a wider range throwsRangeError. A sweep that never manages to load a single page — the shape a blocked or consent-gated client produces — stops once five dates have come back payload-less rather than paying the retry budget on all of them, and throws. Up to ten dates are in flight at once, so around fourteen are attempted before the rest are abandoned (measured: 42 page fetches, whether the range is 30, 61 or 93 days). Only pages served without results count towards that: a timeout or a dropped connection says nothing about the dates not yet tried, so those never abandon a sweep. A sweep cut short that still found prices returns them with one warning saying so. The breaker itself disarms for good the moment any page loads, even an empty one — so it cannot catch a sweep that is mostly timeouts around one lucky date.SearchDates.searchthrows that case too: if nothing priced and at least half the attempted dates never loaded, that is not enough evidence to call the range flight-free. A minority of failures alongside real results, or alongside a confirmed-empty range, still returns normally but logs one warning naming the counts. - A page occasionally arrives without results. Roughly one request in sixty
returns HTTP 200 with no
ds:1blob; the client retries that case up to twice (0.5s then 1.5s) before throwingSearchParseError. A healthy search never pays for it. FLI_SOCS_COOKIE. EU/EEA IPs are redirected to Google's consent interstitial, which serves nods:1blob. The client sends a pre-acceptedSOCSconsent cookie by default; setFLI_SOCS_COOKIEto change the value, or to an empty string to send none.
The client reports dropped filters and partial sweeps through console.warn.
Redirect or silence that with setSearchLogger:
import { setSearchLogger } from "fli-js";
setSearchLogger({ warn: (m) => myLogger.warn(m), debug: () => {} });
setSearchLogger(null); // back to console.warn
HTTP / proxy configuration
The TypeScript port uses native fetch (Bun's and Node's built-in) and
replaces curl_cffi's TLS impersonation with:
- realistic Chrome
User-Agent+Sec-CH-*headers — theUser-Agentis load-bearing, not cosmetic: without one the search page serves a shell with no flight rows in it, - automatic rate-limiting at 10 req/s,
- 3-attempt exponential backoff on transient errors,
- proxy support via the
HTTPS_PROXY/HTTP_PROXYenv vars (or via the explicitproxyoption onnew Client({...})).
import { Client, SearchFlights } from "fli-js";
const search = new SearchFlights(
new Client({ proxy: "http://user:[email protected]:8080" }),
);
Set the per-request timeout with FLI_TIMEOUT=30 (seconds) or via the
timeoutMs option on new Client({...}).
Modules
fli-js/models—Airport,Airline,FlightSearchFilters,DateSearchFilters,FlightSegment,FlightResult,BookingOption, all enums.fli-js/core— string-to-enum parsers, segment builders, airport search, currency token decoders, deep-link builder (googleFlightsUrl).fli-js/search—SearchFlights(incl.buildFlightBookingUrl),SearchDates,Client, error classes, protobuf token helpers (buildBookingToken,buildTfsToken,extractBookingTokenFromTfu), and the search-page transport (buildTfs,pageUrl,extractPayload,fetchPayload).
Development
bun install
bun run generate:enums # regenerate airport.ts / airline.ts from data/*.csv
bun run typecheck
bun run lint # biome + oxlint
bun run format # biome format
bun test # unit + integration tests (no network)
bun run test:e2e # live tests (FLI_E2E=1; talks to Google Flights)
bun run ci # format-check + lint + typecheck + tests
Parity with the Python library
The TypeScript port preserves byte-perfect wire compatibility with the Python upstream:
FlightSearchFilters.format()produces structurally identical nested-list payloads (seetests/integration/filter_format_snapshots.test.ts).buildBookingToken(...)andbuildTfsToken(...)reproduce captured live booking-page tokens byte-for-byte (seetests/search/proto.test.ts); the resultingbuildFlightBookingUrl(...)output matches the Python library character-for-character.buildTfs(...)produces the same search-page token as the Pythonfli.search._tfs.build_tfsacross trip shapes, cabins, stop limits, passenger mixes, alliances and layover bounds. The expected values intests/search/tfs.test.tsare generated by running the Python encoder — regenerate them from the repository root withuv run --python 3.13 python fli-js/scripts/dump_tfs_goldens.py.extractPayload(...)is pinned against the same captured search page the Python suite uses (tests/search/fixtures/search_page_jfk_lhr_nonstop_ds1.html).- The wire-format parser handles both the legacy single-chunk JSONP
shape and the multi-chunk format used by
GetBookingResults.
License
MIT — same as the upstream Python project.