flights

Go library and CLI for searching Google Flights. Scrapes flight data by encoding search parameters as protobuf, hitting the Google Flights HTML endpoint, and decoding the embedded JSON response.

Install

go install github.com/nickvanw/flights/cmd/flights@latest

CLI Usage

flights -origin SEA -dest SFO -date 2026-03-15
flights -origin SEA -dest AMS -date 2026-03-15 -return 2026-03-31
flights -origin SEA -dest JFK -date 2026-03-15 -max-stops 0 -seat business -json

Flags

Flag	Description	Default
-origin	Departure airport (IATA code)	required
-dest	Arrival airport (IATA code)	required
-date	Departure date (YYYY-MM-DD)	required
-return	Return date for round-trip	-
-adults	Number of adults	1
-children	Number of children	0
-seat	economy, premium-economy, business, first	economy
-currency	Currency code	USD
-max-stops	Max stops (-1 = no filter, 0 = nonstop)	-1
-json	JSON output	false

Round-Trip Searches

When -return is specified, the CLI performs a two-phase search matching Google Flights' actual behavior:

1. Fetches all outbound options with round-trip pricing
2. Auto-selects the best outbound, then fetches compatible return options

All prices shown are total round-trip prices. JSON output uses the structure:

{
  "outbound": { "Best": [...], "Other": [...] },
  "return": { "Best": [...], "Other": [...] },
  "selected_outbound": { ... }
}

Library Usage

req := &flights.SearchRequest{
    Legs: []flights.Leg{
        {From: "SEA", To: "SFO", Date: "2026-03-15"},
    },
    Trip:       flights.OneWay,
    Passengers: flights.Passengers{Adults: 1},
    Seat:       flights.Economy,
    Currency:   "USD",
}

result, err := flights.Search(ctx, req)

For round-trip, search outbound first, then call SearchReturn with a selected itinerary:

req := &flights.SearchRequest{
    Legs: []flights.Leg{
        {From: "SEA", To: "AMS", Date: "2026-03-15"},
        {From: "AMS", To: "SEA", Date: "2026-03-31"},
    },
    Trip: flights.RoundTrip,
    // ...
}

outbound, _ := flights.Search(ctx, req)
returnFlights, _ := flights.SearchReturn(ctx, req, outbound.Best[0])

Protobuf

Search parameters are encoded as protobuf and passed via the tfs URL parameter. The proto definitions are in proto/flights.proto. Regenerate with:

make proto

Claude Code Skill

The SKILL.md in this repo provides a /flights skill for Claude Code that acts as a natural language travel assistant — parsing requests like "fly from Seattle to SF next Monday, nonstop, arriving before noon", running searches, filtering results, and presenting options.