Google Flights Search

Google Flights Search

[繁體中文](README_zh.md) | English

 

A lightweight Google Flights client that **actually works for small and regional airports**. Uses a fast SSR path for popular routes; falls back to a Playwright-based stage for regional airports (e.g. Taichung RMQ, Kumamoto KMJ).

Why gf-search instead of fast-flights?

Existing libraries like `fast-flights` silently return empty results for low-traffic airports (e.g. Taichung RMQ, Kumamoto KMJ). The root cause is an **incomplete protobuf URL encoding**: Google receives a malformed request and skips on-demand calculation, returning `data[3] = null`.

`gf-search` reverse-engineered the exact protobuf format Chrome sends, with three critical fixes:

Field	fast-flights	gf-search
Airport.field_1 (entity type)	missing	1 = IATA airport, 2 = city entity ID
Info.field_1, Info.field_2	missing	28, 2 (query type flags)
Info.field_16	missing	INT64_MAX — triggers on-demand calculation for small airports

**Result:** `RMQ → KMJ` returns full flight data including Starlux Airlines (JX) direct flights, whereas fast-flights returns `data[3] = null`.

Installation

Basic (SSR only — works for most popular routes)

pip install google-flights-search

+ Playwright fallback (required for small/regional airports like RMQ, KMJ)

pip install "google-flights-search[playwright]"
playwright install chromium      # download browser binary (~130 MB), one-time
gf-search-setup                  # one-time Google sign-in → saves session

`gf-search-setup` opens a browser window. Sign into your Google account; the session is auto-detected and saved to `~/.flight_agent/session_cookies.json`. All subsequent searches use it automatically — no further setup needed.

Windows: automatic Chrome session extra