{"openapi":"3.1.0","info":{"title":"AirportMiles API","version":"1.0.0","summary":"Airport codes, distances, routes and traffic numbers as static JSON files. No key.","description":"Every response is a static file, rebuilt each month from open data (OurAirports, Wikidata, US DOT / BTS, Eurostat, and the national offices of Brazil, Korea, Australia and India).\n\nNo key and no sign-up; CORS is open. Please cache responses and send a User-Agent that names your app.\n\nLicence: CC0-1.0 for airport, city and geometry fields. Fields listed in a file's `sources` keep that source's terms (name the source).\n\nTime zones are not included (their source is under the ODbL).","license":{"name":"CC0-1.0","identifier":"CC0-1.0"},"contact":{"name":"AirportMiles","url":"https://airportmiles.com/api","email":"hello@airportmiles.com"},"x-logo":{"url":"https://airportmiles.com/logo.png"}},"externalDocs":{"description":"Documentation and examples","url":"https://airportmiles.com/api"},"servers":[{"url":"https://airportmiles.com/api/v1"}],"security":[],"tags":[{"name":"Index","description":"What has a file"},{"name":"Airports","description":"One file per airport, by IATA code"},{"name":"Routes","description":"One file per busy airport pair"},{"name":"Cities","description":"Cities with several airports"},{"name":"Countries","description":"One file per country"}],"paths":{"/index.json":{"get":{"operationId":"getIndex","tags":["Index"],"summary":"Every file","description":"File URL templates, counts, and every airport code, route key, city and country slug that has a file.","parameters":[],"responses":{"200":{"description":"The file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Index"}}}},"404":{"description":"No such file: the code or slug is not in /index.json"}}}},"/airports/{iata}.json":{"get":{"operationId":"getAirport","tags":["Airports"],"summary":"One airport","description":"Codes, names, position, runways, passengers, nonstop routes with distance and passengers, airlines (routes touching the US), punctuality, nearby airports.","parameters":[{"name":"iata","in":"path","required":true,"description":"IATA code, lowercase","schema":{"type":"string","pattern":"^[a-z]{3}$"},"example":"lhr"}],"responses":{"200":{"description":"The file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirportFile"}}}},"404":{"description":"No such file: the code or slug is not in /index.json"}}}},"/routes/{pair}.json":{"get":{"operationId":"getRoute","tags":["Routes"],"summary":"One route","description":"Distance (km, mi, nm, great circle), flight time (estimate and real averages), EU261 / UK261 band each way, CO2, traffic, airlines, aircraft, punctuality, average fares paid and a fare outlook (US domestic), fares sold (Brazil domestic). Only for the busiest pairs listed in /index.json; codes in alphabetical order.","parameters":[{"name":"pair","in":"path","required":true,"description":"Two IATA codes, lowercase, alphabetical, joined by \"-\"","schema":{"type":"string","pattern":"^[a-z]{3}-[a-z]{3}$"},"example":"jfk-lhr"}],"responses":{"200":{"description":"The file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteFile"}}}},"404":{"description":"No such file: the code or slug is not in /index.json"}}}},"/cities/{slug}.json":{"get":{"operationId":"getCity","tags":["Cities"],"summary":"One city with several airports","description":"Its airports, city code, and the distances between them.","parameters":[{"name":"slug","in":"path","required":true,"description":"City slug","schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"example":"london"}],"responses":{"200":{"description":"The file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityFile"}}}},"404":{"description":"No such file: the code or slug is not in /index.json"}}}},"/countries/{slug}.json":{"get":{"operationId":"getCountry","tags":["Countries"],"summary":"One country","description":"Every airport with scheduled flights, busiest first, and its cities with several airports.","parameters":[{"name":"slug","in":"path","required":true,"description":"Country slug: English name, lowercase, hyphens","schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"example":"italy"}],"responses":{"200":{"description":"The file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryFile"}}}},"404":{"description":"No such file: the code or slug is not in /index.json"}}}}},"components":{"schemas":{"Head":{"type":"object","properties":{"api":{"type":"string"},"generated":{"type":"string","format":"date"},"docs":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"},"page":{"type":"string","format":"uri"},"licence":{"type":"string"},"licenceNote":{"type":"string"}}},"Source":{"type":"object","required":["id","name","licence","fields"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"licence":{"type":"string"},"period":{"type":"string"},"fields":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}}},"AirportRef":{"type":"object","properties":{"iata":{"type":"string"},"icao":{"type":["string","null"]},"name":{"type":"string"},"city":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"latitude":{"type":"number"},"longitude":{"type":"number"},"self":{"type":"string","format":"uri"}}},"Passengers":{"type":"object","description":"An official statistics office where one has the airport (Eurostat, T-100, Statistics Canada, ANAC, BITRE, Korea Airports Corporation, MLIT Japan, JAC Chile), else Wikidata (latest full year). period is a year (\"2025\") or a span of months (\"2025-07…2026-06\": T-100, ANAC and JAC, the last 12 months; the smaller BITRE airports, the year to June). previousYear is the year before, or for JAC the 12 months before. Eurostat airports and the 20 busiest BITRE airports add yearToDate: the months reported after that year, with the same months a year before. The matching sources entry: id \"bitre-airports\" for source \"bitre\", else the same id.","properties":{"count":{"type":"integer"},"previousYear":{"type":["integer","null"]},"period":{"type":"string"},"source":{"enum":["eurostat","t100","statcan","anac","bitre","kac","mlit","jac","wikidata"]},"yearToDate":{"type":"object","properties":{"months":{"type":"string","description":"First…last month, e.g. 2026-01…2026-05"},"count":{"type":"integer"},"sameMonthsYearBefore":{"type":"integer"}}}}},"AirportFile":{"allOf":[{"$ref":"#/components/schemas/Head"},{"type":"object","properties":{"airport":{"type":"object","properties":{"iata":{"type":"string"},"icao":{"type":["string","null"]},"name":{"type":"string"},"municipality":{"type":"string"},"city":{"type":"string"},"multiAirportCity":{"type":["object","null"],"properties":{"name":{"type":"string"},"code":{"type":["string","null"]},"self":{"type":"string","format":"uri"},"page":{"type":"string","format":"uri"}}},"country":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"self":{"type":"string","format":"uri"},"page":{"type":"string","format":"uri"}}},"region":{"type":["string","null"]},"continent":{"type":["string","null"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"elevationM":{"type":["integer","null"]},"size":{"enum":["large","medium","small"]},"wikidata":{"type":["string","null"]},"website":{"type":["string","null"]},"wikipedia":{"type":["string","null"]},"opened":{"type":["integer","null"],"description":"Year of the official opening, else of the founding (Wikidata)"},"operator":{"type":"array","items":{"type":"string"},"description":"Who runs it (Wikidata)"},"runways":{"type":"array","items":{"type":"object","properties":{"ids":{"type":"string"},"lengthM":{"type":"integer"},"widthM":{"type":["integer","null"]},"surface":{"type":["string","null"]},"lighted":{"type":"boolean"}}}}}},"passengers":{"oneOf":[{"$ref":"#/components/schemas/Passengers"},{"type":"null"}]},"routes":{"type":"array","items":{"type":"object","properties":{"to":{"$ref":"#/components/schemas/AirportRef"},"km":{"type":"integer"},"passengers":{"type":"integer","description":"Both directions, over the period of its source (see sources)"},"nationalSource":{"type":["string","null"],"enum":["anac","incheon","jac","bitre","dgca",null],"description":"The national office the passengers come from; null: T-100 or Eurostat"},"self":{"type":["string","null"],"format":"uri"},"page":{"type":["string","null"],"format":"uri"}}}},"airlines":{"type":["object","null"],"properties":{"usRoutesOnly":{"type":"boolean"},"period":{"type":"string"},"list":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"flights":{"type":"integer"}}}}}},"punctuality":{"type":["object","null"],"properties":{"period":{"type":"string"},"departures":{"type":"integer"},"onTimePct":{"type":"number"},"cancelledPct":{"type":"number"},"scope":{"type":"string"}}},"cityAirports":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AirportRef"},{"type":"object","properties":{"km":{"type":"integer"}}}]}},"nearby":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AirportRef"},{"type":"object","properties":{"km":{"type":"integer"}}}]}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}}]},"Compensation":{"type":["object","null"],"properties":{"band":{"enum":["short","medium","long"]},"amount":{"type":"integer"},"reducedAmount":{"type":["integer","null"]},"currency":{"enum":["EUR","GBP"]},"airlines":{"enum":["any","eu","uk-or-eu"]}}},"Month":{"type":"object","properties":{"month":{"type":"string","description":"YYYY-MM"},"passengers":{"type":"integer"},"flights":{"type":["integer","null"],"description":"Null where the source counts no flights (national source jac)"}}},"FareCarrier":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"share":{"type":"integer","description":"Share of the market's passengers, %"},"fare":{"type":"integer","description":"That airline's average fare paid, USD"}}},"FareOutlook":{"type":"object","description":"The average fare paid we expect a year after latestQuarter (an estimate, not a price you can book). Only on routes whose past forecasts held; method and backtest at `method`.","properties":{"note":{"type":"string"},"quarter":{"type":"string","description":"The quarter estimated, YYYY-Qn"},"basedOnQuarter":{"type":"string","description":"The newest DOT quarter it starts from"},"avgFareUsd":{"type":"object","properties":{"low":{"type":"integer"},"mid":{"type":"integer"},"high":{"type":"integer"}}},"rangePct":{"type":"integer","description":"The actual average should fall between low and high this often"},"backtest":{"type":"object","description":"How forecasts made the same way did on this route","properties":{"heldPct":{"type":"integer","description":"Actual inside the range, %"},"medianErrorPct":{"type":"number"},"quartersJudged":{"type":"integer"}}},"cheapestTravelQuarter":{"type":["object","null"],"description":"The quarter of travel (not of booking) usually cheapest on this route","properties":{"quarter":{"enum":["Q1","Q2","Q3","Q4"]},"belowPct":{"type":"integer","description":"Below the year's average, %"},"years":{"type":"integer"}}},"method":{"type":"string","format":"uri"}}},"RouteFile":{"allOf":[{"$ref":"#/components/schemas/Head"},{"type":"object","properties":{"key":{"type":"string","description":"The two codes, alphabetical: JFK-LHR"},"from":{"$ref":"#/components/schemas/AirportRef"},"to":{"$ref":"#/components/schemas/AirportRef"},"distance":{"type":"object","properties":{"km":{"type":"integer"},"mi":{"type":"integer"},"nm":{"type":"integer"},"greatCircleKm":{"type":"integer"},"method":{"type":"string"}}},"bearing":{"type":"object","properties":{"fromA":{"type":"integer"},"fromB":{"type":"integer"}}},"midpoint":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"}}},"flightTime":{"type":"object","properties":{"estimateMin":{"type":"integer"},"estimateMethod":{"type":"string"},"directions":{"type":["object","null"],"description":"Keyed \"JFK>LHR\"","additionalProperties":{"type":["object","null"],"properties":{"flights":{"type":"integer"},"passengers":{"type":"integer"},"blockMin":{"type":["integer","null"]},"airMin":{"type":["integer","null"]}}}}}},"compensation":{"type":"object","properties":{"note":{"type":"string"},"directions":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"eu261":{"$ref":"#/components/schemas/Compensation"},"uk261":{"$ref":"#/components/schemas/Compensation"}}}}}},"co2":{"type":"object","properties":{"kgPerPassenger":{"type":"integer"},"kgWithoutRadiativeForcing":{"type":"integer"},"band":{"type":"string"},"scope":{"type":"string"}}},"traffic":{"type":"object","properties":{"t100":{"type":["object","null"],"properties":{"period":{"type":"string"},"passengers":{"type":"integer"},"seats":{"type":"integer"},"flights":{"type":"integer"},"airlines":{"type":"array","items":{"type":"object"}},"aircraft":{"type":"array","items":{"type":"object"}},"months":{"type":"array","items":{"$ref":"#/components/schemas/Month"}}}},"eurostat":{"type":["object","null"],"properties":{"year":{"type":"integer"},"reporter":{"type":"string"},"passengers":{"type":"integer"},"seats":{"type":["integer","null"]},"flights":{"type":["integer","null"]},"months":{"type":"array","items":{"$ref":"#/components/schemas/Month"}}}},"national":{"type":["object","null"],"description":"A national office, only where neither t100 nor eurostat has the route: anac (Brazil), incheon (Incheon Airport, Korea), jac (Chile), bitre (Australia), dgca (India, provisional). BITRE and DGCA report cities, matched to one airport; they name no airlines, and DGCA international has quarters, not months. JAC counts passengers only: seats and flights are null, in airlines and months too.","properties":{"source":{"enum":["anac","incheon","jac","bitre","dgca"]},"period":{"type":"string"},"monthsCounted":{"type":"integer","description":"12, or fewer while a source's archive is young (Incheon publishes half-years)"},"passengers":{"type":"integer"},"passengersPreviousPeriod":{"type":["integer","null"]},"seats":{"type":["integer","null"]},"flights":{"type":["integer","null"]},"airlines":{"type":"array","items":{"type":"object"}},"months":{"type":"array","items":{"$ref":"#/components/schemas/Month"}},"dataset":{"type":["string","null"],"enum":["domestic","international",null]},"note":{"type":["string","null"]},"scope":{"type":"string"}}}}},"punctuality":{"type":["object","null"]},"fares":{"type":["object","null"],"description":"Average fares paid, US domestic: history, not a price","properties":{"note":{"type":"string"},"latestQuarter":{"type":"string","description":"YYYY-Qn"},"latestAvgFareUsd":{"type":"integer"},"passengersPerDay":{"type":"integer"},"largestAirline":{"$ref":"#/components/schemas/FareCarrier"},"lowestFareAirline":{"$ref":"#/components/schemas/FareCarrier"},"yearAvgFareUsd":{"type":"integer","description":"Passenger-weighted over the quarters listed"},"quarters":{"type":"array","items":{"type":"object","properties":{"quarter":{"type":"string"},"avgFareUsd":{"type":"integer"},"passengersPerDay":{"type":"integer"}}}},"outlook":{"oneOf":[{"$ref":"#/components/schemas/FareOutlook"},{"type":"null"}]}}},"faresSold":{"type":["object","null"],"description":"Brazil domestic only (ANAC): fares as sold to the public by month of sale, seat-weighted, one way, BRL, airport fees not included. History, not a price.","properties":{"note":{"type":"string"},"currency":{"enum":["BRL"]},"latestMonth":{"type":"string","description":"YYYY-MM, month of sale"},"latestAvgFare":{"type":"integer"},"latestMedianFare":{"type":"integer"},"latestMiddleHalf":{"type":"object","description":"Quartiles: half the seats sold between low and high","properties":{"low":{"type":"integer"},"high":{"type":"integer"}}},"latestSeatsSold":{"type":"integer"},"yearAvgFare":{"type":"integer"},"yearSeatsSold":{"type":"integer"},"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"avgFare":{"type":"integer"},"seatsSold":{"type":"integer"}}}}}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}}]},"CityFile":{"allOf":[{"$ref":"#/components/schemas/Head"},{"type":"object","properties":{"city":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":["string","null"]},"slug":{"type":"string"},"country":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"wikidata":{"type":["string","null"]},"countryFile":{"type":["string","null"],"format":"uri"}}},"airports":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AirportRef"},{"type":"object","properties":{"size":{"type":"string"},"routes":{"type":"integer"},"passengers":{"oneOf":[{"$ref":"#/components/schemas/Passengers"},{"type":"null"}]}}}]}},"distancesKm":{"type":"array","items":{"type":"array","items":{"type":"integer"}}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}}]},"CountryFile":{"allOf":[{"$ref":"#/components/schemas/Head"},{"type":"object","properties":{"country":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"continent":{"type":["string","null"]}}},"airports":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AirportRef"},{"type":"object","properties":{"size":{"type":"string"},"routes":{"type":"integer"},"passengers":{"oneOf":[{"$ref":"#/components/schemas/Passengers"},{"type":"null"}]}}}]}},"cities":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":["string","null"]},"airports":{"type":"array","items":{"type":"string"}},"self":{"type":"string","format":"uri"}}}},"airFares":{"type":["object","null"],"description":"European countries: Eurostat HICP for passenger transport by air (CP0733), rates of change in %. A price index, not a fare.","properties":{"month":{"type":"string","description":"YYYY-MM"},"avg12Pct":{"type":"number","description":"12 months to `month` against the 12 before"},"annualPct":{"type":"number","description":"`month` against a year earlier"},"note":{"type":"string"}}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}}]},"Index":{"allOf":[{"$ref":"#/components/schemas/Head"},{"type":"object","properties":{"files":{"type":"object","additionalProperties":{"type":"string"}},"notes":{"type":"array","items":{"type":"string"}},"counts":{"type":"object","properties":{"airports":{"type":"integer"},"routes":{"type":"integer"},"cities":{"type":"integer"},"countries":{"type":"integer"}}},"airports":{"type":"array","items":{"type":"string"}},"routes":{"type":"array","items":{"type":"string"}},"cities":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"type":"string"}}}}]}}}}