GET /v1/aviation/airports

Airports within a country, optionally limited to one region, to some types of facility or to airports with scheduled service. With q, the airports anywhere that match a search, best match first. These are the values the airports filter accepts on an Airport field, and on each end of a Flight field.

Request

Query parameter	Required	Default	Description
`country`	Yes, without `q`	none	The country to list airports for, as a two-character code. With `q`, it is optional and limits the search to one country. See GET /v1/aviation/countries for the codes.
`q`	No	none	Text to search for, at least 2 characters. Searches every country unless `country` or `region` is set. See Searching.
`limit`	No	`25`	The most airports a search returns, from 1 to 100. Applies only with `q`.
`region`	No	none	Limits the list to one region. See GET /v1/aviation/regions for the codes.
`type`	No	none	Limits the list to these kinds of facility. Repeat the parameter for more than one. See AirportType for the values.
`scheduledOnly`	No	`false`	Limits the list to airports with scheduled airline service.
`requireIataCode`	No	`false`	Limits the list to airports that have an IATA code.

These parameters apply the same filters as the matching properties of an Airport field, so the list contains exactly the airports such a field can return.

curl "https://api.alchemy.example/v1/aviation/airports?country=gb&scheduledOnly=true" -H "X-Api-Key: YOUR_API_KEY"

curl "https://api.alchemy.example/v1/aviation/airports?country=us&region=US-CO&type=LargeAirport&type=MediumAirport" -H "X-Api-Key: YOUR_API_KEY"

A country can have tens of thousands of airports, most of them heliports and small airfields. Use region, type or scheduledOnly to limit the list to the airports you need.

Searching

With q, the endpoint searches for airports instead of listing a country. The search ignores case, and matches an airport's codes, its name and its municipality. The results are ranked in this order:

An airport whose IATA code, ICAO code or ident is q, so LHR or EGLL returns London Heathrow Airport first.
An airport whose name or municipality starts with q.
An airport whose name or municipality contains q, so heathrow and london both find London Heathrow Airport.

Within each group, airports with scheduled service come first, then large airports before medium airports before small airports before other types, and then the airports are in name order. limit sets how many are returned.

type, scheduledOnly and requireIataCode apply to a search in the same way as to a list. Set scheduledOnly and requireIataCode to search only the airports a Flight field uses. country and region limit the search to one country or one region when they are set.

curl "https://api.alchemy.example/v1/aviation/airports?q=heath&scheduledOnly=true&requireIataCode=true&limit=25" -H "X-Api-Key: YOUR_API_KEY"

[
  {
    "ident": "EGLL",
    "iataCode": "LHR",
    "icaoCode": "EGLL",
    "name": "London Heathrow Airport",
    "type": "LargeAirport",
    "municipality": "London",
    "region": "GB-ENG",
    "country": "GB",
    "scheduled": true
  }
]

A search for london with the same filters and limit=5 returns London Gatwick Airport, London Heathrow Airport, London Luton Airport and London Stansted Airport, which are large airports, and then London City Airport, which is a medium airport. Every name starts with london, so they are in the same group.

A search that matches no airport returns an empty array.

Response

An array of { ident, iataCode, icaoCode, name, type, municipality, region, country, scheduled }. A list is ordered by name, and a search is ordered by how well each airport matches. See Searching.

[
  {
    "ident": "EGPD",
    "iataCode": "ABZ",
    "icaoCode": "EGPD",
    "name": "Aberdeen International Airport",
    "type": "LargeAirport",
    "municipality": "Aberdeen",
    "region": "GB-SCT",
    "country": "GB",
    "scheduled": true
  },
  {
    "ident": "GB-0682",
    "name": "Lydiard Park",
    "type": "Balloonport",
    "region": "GB-ENG",
    "country": "GB",
    "scheduled": false
  }
]

The entries above are an example. Call the endpoint for current values.

Property	Description
`ident`	An identifier that every airport has, including airports with no other code.
`iataCode`	The three-letter IATA code. Omitted where the airport has none.
`icaoCode`	The four-letter ICAO code. Omitted where the airport has none.
`name`	The airport's name.
`type`	The kind of facility. See AirportType.
`municipality`	The town or city the airport serves. Omitted where it is unknown.
`region`	The ISO 3166-2 code of the airport's region.
`country`	The ISO 3166-1 alpha-2 code of the airport's country.
`scheduled`	Whether the airport has scheduled airline service.

Filtering with these values

The airport of an entry in the airports filter is an IATA code, an ICAO code or an ident. Use iataCode where the airport has one, and ident otherwise.

{
  "type": "Airport",
  "airports": [{ "airport": "ABZ" }, { "airport": "EDI" }, { "airport": "GLA" }],
  "map": { "name": { "column": "airport", "dataType": "VarChar" } }
}

Errors

400 with a ProblemDetails body:

Status	When
`400`	`country` is missing without `q`, is not two characters, or has no airports.
`400`	`region` has no airports in `country`.
`400`	A `type` value is not an airport type.
`400`	`q` is shorter than 2 characters.
`400`	`limit` is not from 1 to 100, or is set without `q`.

A request whose filters match no airport in a valid country and region returns an empty array, not an error. So does a search that matches no airport.