June 15, 2026 · 7 min read · Data
Corrected 14 November 2026: the example responses below are what the API returns today; the earlier version showed routes the API does not have (/v1/cities/london, /v1/airports) and made-up answers.
IATA codes lie: a city has many airports, but APIs return one.
A user asks "nearest airport to London." Your API returns LHR. The user is staying near Stansted. They book a cab to Heathrow, spend three hours and £60, and write your product a one-star review. The principal-airport approximation is correct on average and wrong specifically — and specifically is what matters for trip planning.
Cities with multiple airports
A surprising number of major cities have more than one commercial airport, and the choice between them depends on the route, the airline, and where in the city the traveler is staying.
- London (6): LHR (Heathrow, west, the big one), LGW (Gatwick, south, low-cost long-haul), STN (Stansted, north, Ryanair hub), LTN (Luton, north, easyJet hub), LCY (City Airport, business commuters), SEN (Southend, occasional charter).
- New York (3): JFK (international hub, Queens), LGA (domestic, closer to Manhattan), EWR (Newark, United hub, technically New Jersey).
- Tokyo (2): NRT (Narita, far, most international long-haul), HND (Haneda, close, more domestic plus growing international).
- Paris (2): CDG (Charles de Gaulle, north, most flights), ORY (Orly, south, more domestic and southern Europe).
- Moscow (3): SVO, DME, VKO.
- Berlin (1, post-2020): BER consolidated Tegel and Schönefeld. Worth knowing because old itinerary data still references TXL.
- Istanbul (2): IST (new mega-hub on European side, opened 2018), SAW (Sabiha Gökçen, Asian side, low-cost).
- Shanghai (2): PVG (Pudong, international), SHA (Hongqiao, mostly domestic plus Tokyo/Seoul).
- São Paulo (3): GRU (international), CGH (domestic), VCP (Campinas, low-cost).
- Rio (2): GIG (international), SDU (domestic, on the bay).
- Buenos Aires (2): EZE (international), AEP (domestic).
- Seoul (2): ICN (Incheon, international), GMP (Gimpo, domestic plus a few short-haul).
What the API returns
GET /v1/cities/0c921b48-94e3-4e9c-b319-f9c93e5a4625/context
{
"city_id": "0c921b48-94e3-4e9c-b319-f9c93e5a4625",
"name": "London",
"iso_alpha2": "GB",
"airport": null,
...
}
The airport object of the city context route names one
airport where we hold it for the city. For London we hold none
today, so it is null.
Querying alternates
The nearest_airport tool returns the airports nearest
to a city, by straight-line distance:
POST /v1/agent/tool/nearest_airport
{"city_id": "0c921b48-94e3-4e9c-b319-f9c93e5a4625", "n": 6}
{
"target": {"city_id": "0c921b48-...", "name": "London", "lat": 51.50853, "lon": -0.12574},
"airports": [
{"iata": "LCY", "name": "London City Airport", "distance_km": 12.53, ...},
{"iata": "NHT", "name": "RAF Northolt", "distance_km": 20.82, ...},
{"iata": "BQH", "name": "London Biggin Hill Airport", "distance_km": 22.6, ...},
{"iata": "LHR", "name": "London Heathrow Airport", "distance_km": 23.51, ...},
{"iata": "KRH", "name": "Redhill Aerodrome", "distance_km": 32.81, ...},
{"iata": "LGW", "name": "London Gatwick Airport", "distance_km": 40.22, ...}
],
"row_count": 6,
...
}
Each airport row also carries its type (for example
large_airport for Heathrow and Gatwick,
medium_airport for City and Northolt). The list
shows the problem: by distance alone, an air force base and a
business-jet airfield come before Heathrow. Rank by type, by
typical airline mix, or by ground-transit duration — which is
what users actually care about, and which doesn't track
distance.
Why distance-based selection fails
The naive heuristic — "return the airport closest to the city centroid" — produces wrong results in three predictable ways:
- Closest by km isn't closest by minutes. Heathrow is 24km from central London but 15 minutes by Elizabeth Line. Stansted is 60km but a 45-minute Express. City Airport is 11km but no direct rail. The metric the user cares about is door-to-door time, which depends on where they're staying.
- Domestic vs international flights load different airports. A user flying London → Edinburgh probably wants LCY or LHR (BA) or LGW (BA), and definitely doesn't want STN (Ryanair to Edinburgh departs at 6am). The right airport depends on the airline set for the route, not the destination's distance.
- Low-cost carriers sequester themselves. Ryanair operates almost exclusively from STN and LTN. easyJet skews LGW and LTN. Returning LHR for "cheapest flight to Barcelona" is wrong by definition.
The right shape for AI trip planners
For a trip-planning AI, the airport selection should be a function of:
- The route (origin city + destination city + carrier set)
- The user's neighborhood within the city
- Their cost vs convenience preference
- Time of day (LCY has limited evening flights)
The /v1/airports payload gives you the inputs. The selection logic stays in your product because it's the part that encodes your UX opinion. We don't try to make that decision for you — we just make sure you have the data you need to make it correctly.