Google Flights MCP, CLI and Python Library
/**
* Core data models and enums for the Google Flights API.
*
* 1:1 port of fli/models/google_flights/base.py — keeps the same enum
* integer values (the API uses them on the wire) and the same model field
* names.
*/
import { z } from "zod";
import { parseIsoDate } from "../../core/dates.ts";
import type { Airline } from "../airline.ts";
import type { Airport } from "../airport.ts";
// ---------------------------------------------------------------------------
// Enums (numeric values must match the Google Flights wire format)
// ---------------------------------------------------------------------------
export const SeatType = {
ECONOMY: 1,
PREMIUM_ECONOMY: 2,
BUSINESS: 3,
FIRST: 4,
} as const;
export type SeatType = (typeof SeatType)[keyof typeof SeatType];
export const SortBy = {
TOP_FLIGHTS: 0,
BEST: 1,
CHEAPEST: 2,
DEPARTURE_TIME: 3,
ARRIVAL_TIME: 4,
DURATION: 5,
EMISSIONS: 6,
} as const;
export type SortBy = (typeof SortBy)[keyof typeof SortBy];
export const TripType = {
ROUND_TRIP: 1,
ONE_WAY: 2,
MULTI_CITY: 3,
} as const;
export type TripType = (typeof TripType)[keyof typeof TripType];
export const MaxStops = {
ANY: 0,
NON_STOP: 1,
ONE_STOP_OR_FEWER: 2,
TWO_OR_FEWER_STOPS: 3,
} as const;
export type MaxStops = (typeof MaxStops)[keyof typeof MaxStops];
export const EmissionsFilter = {
ALL: 0,
LESS: 1,
} as const;
export type EmissionsFilter = (typeof EmissionsFilter)[keyof typeof EmissionsFilter];
export const Alliance = {
ONEWORLD: "ONEWORLD",
SKYTEAM: "SKYTEAM",
STAR_ALLIANCE: "STAR_ALLIANCE",
} as const;
export type Alliance = (typeof Alliance)[keyof typeof Alliance];
/**
* ISO 4217 currency codes supported by Google Flights' `curr=` URL param.
* Pass any 3-letter ISO 4217 code as a plain string for codes not listed.
*/
export const Currency = {
AED: "AED",
ARS: "ARS",
AUD: "AUD",
BGN: "BGN",
BRL: "BRL",
CAD: "CAD",
CHF: "CHF",
CLP: "CLP",
CNY: "CNY",
COP: "COP",
CZK: "CZK",
DKK: "DKK",
EGP: "EGP",
EUR: "EUR",
GBP: "GBP",
HKD: "HKD",
HUF: "HUF",
IDR: "IDR",
ILS: "ILS",
INR: "INR",
JPY: "JPY",
KRW: "KRW",
MXN: "MXN",
MYR: "MYR",
NOK: "NOK",
NZD: "NZD",
PEN: "PEN",
PHP: "PHP",
PLN: "PLN",
QAR: "QAR",
RON: "RON",
SAR: "SAR",
SEK: "SEK",
SGD: "SGD",
THB: "THB",
TRY: "TRY",
TWD: "TWD",
UAH: "UAH",
USD: "USD",
VND: "VND",
ZAR: "ZAR",
} as const;
export type Currency = (typeof Currency)[keyof typeof Currency];
// ---------------------------------------------------------------------------
// Simple value-type models (validated via Zod)
// ---------------------------------------------------------------------------
export const BagsFilterSchema = z.object({
checked_bags: z.number().int().nonnegative().default(0),
carry_on: z.boolean().default(false),
});
export type BagsFilter = z.infer<typeof BagsFilterSchema>;
export const TimeRestrictionsSchema = z
.object({
earliest_departure: z.number().int().nonnegative().nullable().optional(),
latest_departure: z.number().int().positive().nullable().optional(),
earliest_arrival: z.number().int().nonnegative().nullable().optional(),
latest_arrival: z.number().int().positive().nullable().optional(),
})
.transform((v) => {
// Mirror the Python validator: if earliest > latest, swap.
const out = { ...v };
if (
out.earliest_departure != null &&
out.latest_departure != null &&
out.earliest_departure > out.latest_departure
) {
[out.earliest_departure, out.latest_departure] = [
out.latest_departure,
out.earliest_departure,
];
}
if (
out.earliest_arrival != null &&
out.latest_arrival != null &&
out.earliest_arrival > out.latest_arrival
) {
[out.earliest_arrival, out.latest_arrival] = [out.latest_arrival, out.earliest_arrival];
}
return out;
});
export type TimeRestrictions = z.infer<typeof TimeRestrictionsSchema>;
export const PassengerInfoSchema = z.object({
adults: z.number().int().nonnegative().default(1),
children: z.number().int().nonnegative().default(0),
infants_in_seat: z.number().int().nonnegative().default(0),
infants_on_lap: z.number().int().nonnegative().default(0),
});
export type PassengerInfo = z.infer<typeof PassengerInfoSchema>;
export const PriceLimitSchema = z.object({
max_price: z.number().int().positive(),
currency: z.string().nullable().optional(),
});
export type PriceLimit = z.infer<typeof PriceLimitSchema>;
export const LayoverRestrictionsSchema = z.object({
airports: z.array(z.string()).nullable().optional(),
min_duration: z.number().int().positive().nullable().optional(),
max_duration: z.number().int().positive().nullable().optional(),
});
export type LayoverRestrictions = z.infer<typeof LayoverRestrictionsSchema>;
/** In-seat power flavour decoded from the leg[12] power slot group. */
export const POWER_TYPES = ["plug_and_usb", "plug", "usb"] as const;
export type PowerType = (typeof POWER_TYPES)[number];
/** In-flight entertainment flavour decoded from the leg[12] video group. */
export const VIDEO_TYPES = ["live_tv", "on_demand", "stream_to_device"] as const;
export type VideoType = (typeof VIDEO_TYPES)[number];
/** Whether Google flags the leg's Wi-Fi as complimentary or chargeable. */
export const WIFI_TIERS = ["free", "paid"] as const;
export type WifiTier = (typeof WIFI_TIERS)[number];
/**
* Human-readable label for Google's leg[13] seat-quality code.
*
* These are labels, not an ordered score: "average"/"below_average"/
* "above_average" describe an economy-style pitch, while the remaining four
* name a seat *product*. The code tracks the fare's cabin rather than the
* airframe — in the captured fixtures AA 1209 (ORD-LAX, 737 MAX 8) appears
* twice, as "average" in economy and "recliner" in first.
*/
export const SEAT_QUALITIES = [
"average",
"below_average",
"above_average",
"extra_reclining",
"lie_flat",
"lie_flat_suite_with_door",
"recliner",
] as const;
export type SeatQuality = (typeof SEAT_QUALITIES)[number];
/**
* Per-leg amenities reported by Google Flights. Booleans are tri-state
* (true / false / null when Google did not publish that signal).
*
* Google never publishes an explicit "no" for any of these amenities — the
* wire format only ever sets a flag or omits it — so `false` is always an
* inference and is used exactly once: `in_seat_video` is false when
* `video_type === "stream_to_device"`, which is Google's way of saying the
* aircraft has no seatback screen. Every other unknown stays null,
* including `usb_power` for a plug-only cabin and `on_demand_video` for a
* live-TV or stream-to-device leg.
*/
export const AmenitiesSchema = z.object({
wifi: z.boolean().nullable().optional(),
power: z.boolean().nullable().optional(),
usb_power: z.boolean().nullable().optional(),
in_seat_video: z.boolean().nullable().optional(),
on_demand_video: z.boolean().nullable().optional(),
legroom_rating: z.number().int().nonnegative().nullable().optional(),
// Optional detail — populated only for slot values confirmed against
// captured responses, so callers never see a confidently wrong label.
wifi_tier: z.enum(WIFI_TIERS).nullable().optional(),
power_type: z.enum(POWER_TYPES).nullable().optional(),
video_type: z.enum(VIDEO_TYPES).nullable().optional(),
seat_quality: z.enum(SEAT_QUALITIES).nullable().optional(),
legroom_inches: z.number().int().positive().nullable().optional(),
});
export type Amenities = z.infer<typeof AmenitiesSchema>;
export interface Layover {
airport: Airport;
duration: number;
overnight: boolean;
change_of_airport: boolean;
city?: string | null;
airport_name?: string | null;
}
export interface FlightLeg {
airline: Airline;
flight_number: string;
departure_airport: Airport;
arrival_airport: Airport;
departure_datetime: Date;
arrival_datetime: Date;
duration: number;
departure_airport_name?: string | null;
arrival_airport_name?: string | null;
operating_airline?: Airline | null;
operating_flight_number?: string | null;
aircraft?: string | null;
legroom?: string | null;
legroom_short?: string | null;
amenities?: Amenities | null;
overnight?: boolean;
co2_emissions_g?: number | null;
/**
* Cabin actually flown on this leg, from leg[16]. Per-leg, so a business
* itinerary can still show an economy connecting leg.
*/
cabin?: SeatType | null;
}
export interface BookingOption {
vendor_code: string | null;
vendor_name: string | null;
is_airline_direct: boolean;
price: number | null;
currency: string | null;
fare_name: string | null;
booking_url: string | null;
google_click_url: string | null;
/** [(airline_code, flight_number), ...] */
flights: Array<[string, string]> | null;
}
export interface FlightResult {
legs: FlightLeg[];
/** Price in specified currency. `null` when Google did not surface a price (see Python issue #165). */
price: number | null;
currency: string | null;
/** Total duration in minutes. */
duration: number;
stops: number;
layovers?: Layover[] | null;
co2_emissions_g?: number | null;
co2_emissions_typical_g?: number | null;
co2_emissions_delta_pct?: number | null;
/** "lower" | "typical" | "higher" */
emissions_tag?: string | null;
self_transfer?: boolean | null;
mixed_cabin?: boolean | null;
primary_airline?: Airline | null;
primary_airline_name?: string | null;
booking_token?: string | null;
}
/** `true` when Google did not surface a price for this row (premium-cabin RT). */
export function priceUnknown(f: FlightResult): boolean {
return f.price == null;
}
// ---------------------------------------------------------------------------
// FlightSegment — input parameter, validated up front
// ---------------------------------------------------------------------------
/**
* Airport entry inside a segment's departure/arrival list — `[Airport code, 0]`
* is the standard shape (the trailing int is unused in current API responses
* but Google still requires it).
*/
export type AirportEntry = [Airport, number];
export interface FlightSegmentInput {
departure_airport: AirportEntry[][];
arrival_airport: AirportEntry[][];
travel_date: string;
time_restrictions?: TimeRestrictions | null;
selected_flight?: FlightResult | null;
}
function todayUtc(): Date {
const now = new Date();
return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
}
export class FlightSegment {
readonly departure_airport: AirportEntry[][];
readonly arrival_airport: AirportEntry[][];
travel_date: string;
readonly time_restrictions: TimeRestrictions | null;
selected_flight: FlightResult | null;
constructor(input: FlightSegmentInput) {
if (!input.departure_airport?.length || !input.arrival_airport?.length) {
throw new Error("Both departure and arrival airports must be specified");
}
// travel_date must be a valid ISO date and not in the past.
const travelDate = parseIsoDate(input.travel_date);
if (travelDate < todayUtc()) {
throw new Error("Travel date cannot be in the past");
}
const depFirst = input.departure_airport[0]?.[0]?.[0];
const arrFirst = input.arrival_airport[0]?.[0]?.[0];
if (depFirst && arrFirst && depFirst === arrFirst) {
throw new Error("Departure and arrival airports must be different");
}
this.departure_airport = input.departure_airport;
this.arrival_airport = input.arrival_airport;
this.travel_date = input.travel_date;
this.time_restrictions = input.time_restrictions ?? null;
this.selected_flight = input.selected_flight ?? null;
}
get parsed_travel_date(): Date {
return parseIsoDate(this.travel_date);
}
}