Airlines and airports

Segment origin, destination, marketing_carrier and operating_carrier are IATA codes. These routes turn a code into a name, a logo, a city or a time zone. Both directories are learned from the supplier as they are used: a code nobody has asked for yet is imported on its first lookup and served from our table afterwards, so there is no catalogue to sync and no stale copy to refresh.

Airlines

GET /v1/flight/airlines searches the learned carriers. q is a literal, case-insensitive substring of the name, IATA or ICAO code; alliance is an exact identifier such as oneworld; active_only defaults to true; limit is 20 by default and 100 at most, with meta.truncated when more matched. GET /v1/flight/airlines/iatas returns every learned code and name with no limit, active ones unless active_only=false. Neither list calls the supplier.

GET /v1/flight/airlines/iatas/{iataCode} reads one carrier, inactive ones included. A code the table lacks is asked of the supplier once: an unknown code is a 404, a supplier failure a 502 supplier_unreachable.

curl "$BASE_URL/v1/flight/airlines/iatas/AF" \
  -H "x-api-key: $API_KEY"

{ "data": { "id": "aln_0192f3a4b5c64d7e8f9a0b1c2d3e4f5d", "iata_code": "AF", "icao_code": "AFR", "name": "Air France", "country": "France", "alliance": "skyteam", "logo_url": "https://production.nuitee.flights/static/images/airlines/AF.png", "is_active": true } }

Booking responses already carry the airline's name in marketing_carrier and its logo in marketing_carrier_logo_url; use the directory when you show a carrier outside a booking.

Airports

GET /v1/flight/airports?q= asks the supplier on every call, within an eight-second budget that covers retries, stores the page it returns and answers in the supplier's order. q is two to one hundred characters and matches name, city or code; limit is 20 by default and 100 at most, with meta.truncated when more matched. A response with no records is an empty list. Unusable records only, a failure or an exceeded budget is a 502 supplier_unreachable.

curl "$BASE_URL/v1/flight/airports?q=new%20york&limit=3" \
  -H "x-api-key: $API_KEY"

{ "data": [ { "id": "apt_0192f3a4b5c64d7e8f9a0b1c2d3e4f5e", "iata_code": "JFK", "icao_code": "KJFK", "name": "John F Kennedy International Airport", "city": "New York", "state": "New York", "country": "United States", "latitude": 40.63980103, "longitude": -73.77890015, "time_zone": "America/New_York" } ], "meta": { "truncated": true } }

GET /v1/flight/airports/iatas/{iataCode} serves a stored airport, or asks the supplier once for a code the table lacks: 404 when it is unknown, 502 when the supplier fails. A value the supplier leaves out, or that would not pass our checks, is null; time_zone is an IANA name you can hand to a date library.

Keep learning