fast-flights-ts

Fast, strongly-typed Google Flights scraper for Node.js. Calls Google's internal RPC endpoint directly -- no HTML scraping, no browser required.

npm install fast-flights-ts

Forked from AWeirdDev/flights (Python). Ported to TypeScript by Claude Opus 4.6.

Quick start

import { createQuery, Passengers, getFlights } from "fast-flights-ts";

const query = createQuery({
  flights: [
    { date: "2026-05-25", from_airport: "GIG", to_airport: "SFO" },
  ],
  seat: "economy",
  trip: "one-way",
  passengers: new Passengers({ adults: 1 }),
  currency: "USD",
});

const results = await getFlights(query);

for (const flight of results) {
  console.log(
    flight.airlines.join(", "),
    `$${flight.price}`,
    flight.flights.map((f) => `${f.from_airport.code}->${f.to_airport.code}`).join(" "),
  );
}

Multi-city

Multi-city and open-jaw queries work out of the box:

const query = createQuery({
  flights: [
    { date: "2026-05-21", from_airport: "GIG", to_airport: "LAX" },
    { date: "2026-05-28", from_airport: "SFO", to_airport: "GIG" },
  ],
  seat: "business",
  trip: "multi-city",
  passengers: new Passengers({ adults: 1 }),
});

const results = await getFlights(query);

Options

getFlights and fetchFlightsHtml accept a second argument:

const results = await getFlights(query, {
  timeout: 15_000,       // ms, default 30s
  maxRetries: 3,         // retry on 429/503/timeout, default 0
  retryDelay: 2_000,     // base delay with exponential backoff + jitter
  signal: controller.signal, // external AbortSignal
  debug: true,           // log to console
});

Integrations

Bright Data

When using an integration, the library falls back to HTML scraping:

import { getFlights, BrightData } from "fast-flights-ts";

const results = await getFlights(query, {
  integration: new BrightData({ api_key: "your-key" }),
});

Env vars: BRIGHT_DATA_API_KEY, BRIGHT_DATA_API_URL, BRIGHT_DATA_SERP_ZONE.

API

createQuery(options)

Option	Type	Default
flights	FlightQueryInput[]	required
seat	"economy" | "premium-economy" | "business" | "first"	"economy"
trip	"round-trip" | "one-way" | "multi-city"	"one-way"
passengers	Passengers	1 adult
language	Language | ""	""
currency	Currency | ""	""
max_stops	number | null	null

getFlights(query, options?)

Returns Promise<FlightResults> -- an array of Flights with attached metadata.

Passengers

new Passengers({ adults: 2, children: 1, infants_in_seat: 0, infants_on_lap: 0 })

Max 9 total. Infants on lap cannot exceed adult count.

Error handling

All errors extend FlightError:

import { FlightError, HttpError, CaptchaError, TimeoutError, ParseError } from "fast-flights-ts";

try {
  await getFlights(query);
} catch (e) {
  if (e instanceof TimeoutError) { /* request timed out */ }
  if (e instanceof HttpError) { /* e.status, e.responseLength */ }
  if (e instanceof CaptchaError) { /* Google wants a CAPTCHA */ }
  if (e instanceof ParseError) { /* unexpected response format */ }
}

Retry is automatic for 429, 502, 503, 504, and timeouts when maxRetries > 0.

Response types

interface Flights {
  type: string;
  price: number;
  airlines: string[];
  flights: SingleFlight[];
  carbon: CarbonEmission;
}

interface SingleFlight {
  from_airport: Airport; // { code, name }
  to_airport: Airport;
  departure: SimpleDatetime;
  arrival: SimpleDatetime;
  duration: number; // minutes
  plane_type: string;
}

interface FlightResults extends Array<Flights> {
  metadata: JsMetadata; // { airlines, alliances }
}

Benchmarks

Compared against the original Python implementation v3 (10,000 iterations, bash bench/cross-lang.sh).

Encoding (query + protobuf + base64)

	ops/sec	latency
Python v3	214,626	4.7 us
TypeScript	462,181	2.2 us

2.2x faster.

Parsing (20-flight payload, JSON extract + mapping)

	ops/sec	latency
Python v3	17,711	56.5 us
TypeScript	53,911	18.5 us

3.0x faster.

Detailed breakdown (npm run bench)

Operation	ops/sec	mean
encodeInfo (simple)	833,718	1.2 us
encodeInfo (complex)	341,613	2.9 us
encodeInfoToBase64	768,435	1.3 us
createQuery	16,330,189	0.06 us
createQuery + toStr()	728,724	1.4 us
parseRpcResponse (5 flights)	151,354	6.6 us
parseRpcResponse (50 flights)	17,604	56.8 us
parseRpcResponse (200 flights)	4,368	229 us

How it works

1. Query -- builds flight parameters (dates, airports, seat, passengers)
2. RPC -- POSTs directly to Google's GetShoppingResults endpoint
3. Parse -- strips )]}' prefix, extracts nested JSON with flight data
4. Fallback -- HTML scraping via node-libcurl or fetch when using integrations

The RPC approach is used by default for structured queries. It works for all trip types (one-way, round-trip, multi-city) and returns more results than HTML scraping (best + other flights).

Why it's fast

• Direct RPC -- no HTML to download or parse, ~35KB response vs ~2MB HTML
• Manual protobuf encoder (~80 lines, no protobufjs)
• Zero runtime dependencies -- node-libcurl is optional
• 20 KB bundled (ESM + CJS dual output)

Development

npm install
npm run typecheck
npm test            # 21 tests
npm run bench
npm run build

License

MIT -- see LICENSE.

Original Python library by AWeirdDev. RPC approach inspired by swoop.