Table of Contents

Airport

Generates a real airport, with its codes, its location, its elevation, its time zone and its position.

Use it for columns that contain an airport, such as an origin or destination code or a home base. For a journey between two airports, with an airline, a schedule and a route, use Flight, which selects both ends from the same airports.

Sub-fields: at least one must be mapped. See Sub-fields.

Every JSON block on this page is a single field object, one entry in a table's fields array. See Building a Request for the full request structure.

Sub-fields

Sub-field Produces
address The municipality, region and country as one line, e.g. London, England, United Kingdom. See Elevation and position.
continent The continent code, e.g. EU. See Continents.
country The ISO 3166-1 alpha-2 country code, e.g. GB.
countryName The full country name, e.g. United Kingdom.
elevationFeet The elevation in feet, e.g. 83. Null where the elevation is unknown.
elevationMeters The elevation in meters, rounded to one decimal place, e.g. 25.3. Null where the elevation is unknown.
gpsCode The code used for navigation, usually the same as the ICAO code, e.g. EGLL. Null where the airport has none.
iataCode The three-letter IATA code, e.g. LHR. Null where the airport has none.
icaoCode The four-letter ICAO code, e.g. EGLL. Null where the airport has none.
ident An identifier that every airport has, including airports with no other code, e.g. EGLL or US-8364.
latitude The latitude as a number, rounded to precision, e.g. 51.470748. Map it to a Double or Float column.
localCode The national code, where the country issues one, e.g. LS73. Null where the airport has none.
location The airport's position as WKT, rounded to precision, e.g. POINT(-0.459909 51.470748). Map it to a Geometry column.
longitude The longitude as a number, rounded to precision, e.g. -0.459909. Map it to a Double or Float column.
municipality The town or city the airport serves, e.g. London.
name The airport's name, e.g. London Heathrow Airport.
region The ISO 3166-2 subdivision code, e.g. GB-ENG.
regionName The subdivision's name, e.g. England.
timeZone The airport's time zone, e.g. Europe/London. See Time zone.
type The kind of facility, in lowercase with underscores, e.g. large_airport or heliport. See AirportType.

iataCode, icaoCode, gpsCode, localCode and ident are the airport's codes. See Codes.

elevationFeet and elevationMeters are the same elevation in two units. latitude, longitude and location are the same point, as two numbers or as a geometry. See Elevation and position.

Properties

Property Type Default Description
airports AirportWeight[]? none Limits the field to these airports, each with a weight. Cannot be combined with countries or regions. See Specific airports and Weighting.
continents string[]? none Limits the field to airports on these continents. See Continents.
countries CountryWeight[]? none Limits the field to airports in these countries, each with a weight. Cannot be combined with regions or airports. See Weighting.
map object required Maps the field's sub-fields to destination columns. See Building a Request.
nullPercentageMax number 0 Upper bound (0-100) of the percentage of rows that should be null. See nullPercentageMin.
nullPercentageMin number 0 Lower bound (0-100) of the percentage of rows that should be null. The rate is fixed once for the whole field from this range, not recalculated per row. Set equal to nullPercentageMax for an exact rate.
precision integer 6 How many decimal places latitude, longitude and location are rounded to, from 0 to 15, where 0 uses the default.
regions AirportRegionWeight[]? none Limits the field to airports in these subdivisions, each with a weight. Cannot be combined with countries or airports. See Weighting.
requireIataCode boolean false Limits the field to airports that have an IATA code. See Airports with scheduled service.
scheduledOnly boolean false Limits the field to airports with scheduled airline service.
seed integer random Per-field seed, overriding the request's own seed for this field only.
types AirportType[]? none Limits the field to these kinds of facility. With no types, every kind is included, including closed facilities.
unique boolean false Whether every generated airport must differ from the others. Limited by the number of airports that match the filters. A request for more unique rows than the field can produce is rejected before any data is generated, stating how many are available.

Codes are matched without regard to case, so us and US are both accepted.

An airport must match every filter that is set. Within a list, an airport must match one entry. For example, with countries set to France and Germany and types set to ["LargeAirport"], the field returns large airports in France or Germany.

Only one of countries, regions and airports can be set, because every region and airport is already in one country. Each entry must match at least one airport under the other filters, and an entry that matches none is rejected before any data is generated:

{
  "type": "urn:alchemy:error:invalid-generation-request",
  "title": "Invalid generation request.",
  "status": 400,
  "detail": "No airport matched country ZZ."
}

AirportRegionWeight

Property Type Default Description
region string required The ISO 3166-2 code of the subdivision, matched without regard to case, such as US-CA. See GET /v1/aviation/regions.
weight number 1 The subdivision's relative weight in the distribution, against the other entries. Must be greater than 0.

AirportType

Type Facility
LargeAirport A major airport, almost always with scheduled service and an IATA code.
MediumAirport A regional airport.
SmallAirport A small airfield, usually general aviation only.
Heliport A heliport.
SeaplaneBase A water landing area.
Balloonport A balloon launch site.
Closed A facility that has closed. Use it for historical records.

AirportWeight

Property Type Default Description
airport string required The IATA code, ICAO code or ident of the airport, matched without regard to case, such as LHR or EGLL. See GET /v1/aviation/airports.
weight number 1 The airport's relative weight in the distribution, against the other entries. Must be greater than 0.

Continents

Code Continent
AF Africa
AN Antarctica
AS Asia
EU Europe
NA North America
OC Oceania
SA South America

CountryWeight

Property Type Default Description
country string required The ISO 3166-1 alpha-2 code of the country, matched without regard to case. A code that is not two characters is rejected. See GET /v1/aviation/countries.
weight number 1 The country's relative weight in the distribution, against the other entries. Must be greater than 0.

Weighting

countries, regions and airports are weighted lists. Each entry's weight is relative to the other entries in the same list. It is not a percentage and the weights need not add up to any total, so weights of 3 and 1 give the first entry three rows for every one the second gets. An entry with no weight counts as 1, so a list with no weights set shares the rows evenly among its entries, however many airports each one has.

List How rows are shared
countries Among the countries, by weight. Within a country, every matching airport has the same chance.
regions Among the subdivisions, by weight. Within a subdivision, every matching airport has the same chance.
airports Among the airports, by weight.

Weighted countries

{
  "type": "Airport",
  "countries": [
    { "country": "gb", "weight": 3 },
    { "country": "ie" }
  ],
  "scheduledOnly": true,
  "requireIataCode": true,
  "map": {
    "iataCode": { "column": "code", "dataType": "Char" },
    "name": { "column": "name", "dataType": "VarChar" },
    "countryName": { "column": "country", "dataType": "VarChar" }
  }
}
code name country
IIA Inishmaan Aerodrome Ireland
HUY Humberside Airport United Kingdom
PPW Papa Westray Airport United Kingdom
MAN Manchester Airport United Kingdom
DUB Dublin Airport Ireland
LPL Liverpool John Lennon Airport United Kingdom
INQ Inisheer Aerodrome Ireland
EOI Eday Airport United Kingdom

The United Kingdom has many more airports with scheduled service than Ireland, but the weights, not the number of airports, decide how the rows are shared.

Weighted airports

{
  "type": "Airport",
  "airports": [
    { "airport": "LHR", "weight": 5 },
    { "airport": "LGW", "weight": 3 },
    { "airport": "STN" },
    { "airport": "LTN" }
  ],
  "map": {
    "iataCode": { "column": "code", "dataType": "Char" },
    "name": { "column": "name", "dataType": "VarChar" }
  }
}
code name
LHR London Heathrow Airport
LHR London Heathrow Airport
LHR London Heathrow Airport
LHR London Heathrow Airport
LGW London Gatwick Airport
LGW London Gatwick Airport
LHR London Heathrow Airport
LGW London Gatwick Airport

Heathrow has half the weight, so it fills about half the rows. Stansted and Luton each fill about one row in ten, so a short sample can leave them out.

Airports with scheduled service

Most facilities are not commercial airports. Heliports, private airstrips, seaplane bases and closed facilities are all included, and most of them have no IATA code.

Without scheduledOnly or requireIataCode, iataCode is null for most rows. See All codes for all facility types.

For itineraries and bookings, set both scheduledOnly and requireIataCode. The field then returns only airports with scheduled airline service, and every row has an IATA code:

{
  "type": "Airport",
  "countries": [{ "country": "us" }],
  "scheduledOnly": true,
  "requireIataCode": true,
  "map": {
    "iataCode": { "column": "code", "dataType": "Char" },
    "icaoCode": { "column": "icao", "dataType": "Char" },
    "name": { "column": "name", "dataType": "VarChar" },
    "type": { "column": "type", "dataType": "VarChar" },
    "municipality": { "column": "city", "dataType": "VarChar" },
    "region": { "column": "region", "dataType": "VarChar" }
  }
}
code icao name type city region
KEB Nanwalek Airport small_airport Nanwalek US-AK
SBY KSBY Salisbury Ocean City Wicomico Regional Airport medium_airport Salisbury US-MD
UNK PAUN Unalakleet Airport medium_airport Unalakleet US-AK
ORH KORH Worcester Regional Airport medium_airport Worcester US-MA
EWR KEWR Newark Liberty International Airport large_airport Newark US-NJ
CEM PACE Central Airport small_airport Central US-AK

Scheduled service is not limited to large airports. Small airfields with scheduled flights are included, and some of them have no ICAO code. Add types to limit the field to larger airports.

Codes

Sub-field Code
iataCode The three-letter code used on tickets and baggage tags. Most facilities that are not commercial airports have none.
icaoCode The four-letter code used in air traffic control and flight planning. More airports have an ICAO code than an IATA code, but not every airport has one.
gpsCode The code used for navigation, usually the same as the ICAO code.
localCode The national code, where the country issues one.
ident An identifier that every airport has, including airports with no other code.

A code the airport does not have is null, not an empty string.

Elevation and position

elevationMeters is elevationFeet converted to meters and rounded to one decimal place. Where the elevation is unknown, both are null rather than 0, because 0 is a valid elevation at sea level.

latitude and longitude are numbers rounded to precision, and location is the same point as a geometry. Map the two numbers to numeric columns, location to a spatial column, or all three.

{
  "type": "Airport",
  "countries": [{ "country": "jp" }],
  "scheduledOnly": true,
  "requireIataCode": true,
  "precision": 5,
  "map": {
    "iataCode": { "column": "code", "dataType": "Char" },
    "name": { "column": "name", "dataType": "VarChar" },
    "address": { "column": "address", "dataType": "VarChar" },
    "latitude": { "column": "latitude", "dataType": "Double" },
    "longitude": { "column": "longitude", "dataType": "Double" },
    "location": { "column": "location", "dataType": "Geometry" }
  }
}
code name address latitude longitude location
FSZ Mount Fuji Shizuoka Airport Makinohara / Shimada, Shizuoka Prefecture, Japan 34.79502 138.19098 POINT(138.19098 34.79502)
KKX Kikai Airport Kikai, Kagoshima Prefecture, Japan 28.3213 129.92799 POINT(129.92799 28.3213)
FUJ Fukue Airport Goto, Nagasaki Prefecture, Japan 32.6663 128.83299 POINT(128.83299 32.6663)
KCZ Kochi Ryoma Airport Nankoku, Kōchi Prefecture, Japan 33.54522 133.67017 POINT(133.67017 33.54522)
ONJ Odate Noshiro Airport Kitaakita, Akita Prefecture, Japan 40.1919 140.371 POINT(140.371 40.1919)
SHB Nakashibetsu Airport Nakashibetsu, Hokkaidō Prefecture, Japan 43.5775 144.96001 POINT(144.96001 43.5775)

address contains the municipality, the region name and the country name, in that order. A part the airport does not have is left out, and so is a part that repeats an earlier one, so the line has no empty or duplicate segments.

Airport has no boundingLocation, boundingPolygon or radius. Use countries, regions and continents to limit airports by place.

Time zone

timeZone is the airport's time zone name, such as Europe/Madrid. A Flight field uses the same time zone for the local departure and arrival times at each airport.

{
  "type": "Airport",
  "continents": ["EU"],
  "types": ["LargeAirport"],
  "scheduledOnly": true,
  "requireIataCode": true,
  "map": {
    "iataCode": { "column": "code", "dataType": "Char" },
    "icaoCode": { "column": "icao", "dataType": "Char" },
    "name": { "column": "name", "dataType": "VarChar" },
    "municipality": { "column": "city", "dataType": "VarChar" },
    "countryName": { "column": "country", "dataType": "VarChar" },
    "timeZone": { "column": "time_zone", "dataType": "VarChar" },
    "elevationFeet": { "column": "elevation_ft", "dataType": "Integer" }
  }
}
code icao name city country time_zone elevation_ft
KRS ENCN Kristiansand Airport Kristiansand(Kjevik) Norway Europe/Oslo 57
VLC LEVC Valencia Airport Valencia Spain Europe/Madrid 240
GVA LSGG Geneva International Airport Geneva Switzerland Europe/Zurich 1411
MMX ESMS Malmö Sturup Airport Malmö Sweden Europe/Stockholm 236
LPI ESSL Linköping City Airport Linköping Sweden Europe/Stockholm 172
DUS EDDL Düsseldorf Airport Düsseldorf Germany Europe/Berlin 147

Specific airports

airports limits the field to a fixed list. Each entry is matched against the IATA code, the ICAO code and ident, so LHR and EGLL select the same airport. GET /v1/aviation/airports lists the airports in a country with their codes.

{
  "type": "Airport",
  "airports": [
    { "airport": "LHR" },
    { "airport": "CDG" },
    { "airport": "AMS" },
    { "airport": "FRA" },
    { "airport": "MAD" }
  ],
  "map": {
    "iataCode": { "column": "hub", "dataType": "Char" },
    "name": { "column": "hub_name", "dataType": "VarChar" }
  }
}
hub hub_name
FRA Frankfurt Main Airport
CDG Charles de Gaulle International Airport
AMS Amsterdam Airport Schiphol
MAD Adolfo Suárez Madrid–Barajas Airport
LHR London Heathrow Airport

Every entry has a weight of 1 here, so each airport fills about the same share of rows. See Weighting to favor some airports over others.

An entry that matches no airport is rejected. The other filters still apply, so with types set, each listed airport must also be one of those types.

Examples

Each example below is a single field object, one entry in a table's fields array within a full request. See Building a Request for how it fits into a full DatasetRequest.

Commercial airports in one country

Airports with scheduled airline service and an IATA code, with the city and state each one serves.

{
  "type": "Airport",
  "countries": [{ "country": "au" }],
  "scheduledOnly": true,
  "requireIataCode": true,
  "map": {
    "iataCode": { "column": "code", "dataType": "Char" },
    "name": { "column": "name", "dataType": "VarChar" },
    "municipality": { "column": "city", "dataType": "VarChar" },
    "regionName": { "column": "state", "dataType": "VarChar" }
  }
}
code name city state
BNK Ballina Byron Gateway Airport Ballina New South Wales
XMY Yam Island Airport Yam Island Queensland
CPD Coober Pedy Airport Coober Pedy South Australia
BWT Wynyard Airport Burnie Tasmania
XTG Thargomindah Airport Thargomindah Queensland
WYA Whyalla Airport Whyalla South Australia

All codes for all facility types

With no types, scheduledOnly or requireIataCode, most rows are small airfields, heliports and closed facilities. Most of these have no IATA or ICAO code, so those columns are null. ident is populated on every row.

{
  "type": "Airport",
  "regions": [{ "region": "US-CO" }],
  "seed": 3,
  "map": {
    "ident": { "column": "ident", "dataType": "VarChar" },
    "iataCode": { "column": "iata", "dataType": "Char" },
    "icaoCode": { "column": "icao", "dataType": "Char" },
    "gpsCode": { "column": "gps", "dataType": "VarChar" },
    "localCode": { "column": "local", "dataType": "VarChar" },
    "type": { "column": "type", "dataType": "VarChar" }
  }
}
ident iata icao gps local type
US-11181 closed
KLIC LIC KLIC KLIC LIC small_airport
0CO0 0CO0 0CO0 heliport
KEGE EGE KEGE KEGE EGE medium_airport
8CO7 8CO7 8CO7 small_airport
CO45 CO45 CO45 heliport
24CO closed
US-7997 closed

The two airports with an IATA code have every code. The heliports and the other small airfield have a GPS code and a local code, and the closed facilities have only an ident.

Airports on one continent, with elevation

{
  "type": "Airport",
  "continents": ["SA"],
  "types": ["LargeAirport", "MediumAirport"],
  "scheduledOnly": true,
  "map": {
    "iataCode": { "column": "code", "dataType": "Char" },
    "name": { "column": "name", "dataType": "VarChar" },
    "countryName": { "column": "country", "dataType": "VarChar" },
    "elevationMeters": { "column": "elevation_m", "dataType": "Double" }
  }
}
code name country elevation_m
PHB Parnaíba - Prefeito Doutor João Silva Filho International Airport Brazil 7
CXJ Hugo Cantergiani Regional Airport Brazil 753.5
ASU Silvio Pettirossi International Airport Paraguay 89
CBB Jorge Wilsterman International Airport Bolivia 2548.1
AFL Piloto Osvaldo Marques Dias Airport Brazil 289
IGU Cataratas International Airport Brazil 239.6

Unique airports from a list

With unique, every row has a different airport from airports. A table with more rows than the list contains is rejected before any data is generated.

{
  "type": "Airport",
  "airports": [
    { "airport": "LHR" },
    { "airport": "CDG" },
    { "airport": "AMS" },
    { "airport": "FRA" },
    { "airport": "MAD" }
  ],
  "unique": true,
  "map": {
    "iataCode": { "column": "hub", "dataType": "Char" },
    "name": { "column": "hub_name", "dataType": "VarChar" },
    "timeZone": { "column": "time_zone", "dataType": "VarChar" }
  }
}
hub hub_name time_zone
MAD Adolfo Suárez Madrid–Barajas Airport Europe/Madrid
FRA Frankfurt Main Airport Europe/Berlin
AMS Amsterdam Airport Schiphol Europe/Amsterdam
CDG Charles de Gaulle International Airport Europe/Paris
LHR London Heathrow Airport Europe/London

Seaplane bases with their positions

{
  "type": "Airport",
  "countries": [{ "country": "ca" }],
  "types": ["SeaplaneBase"],
  "map": {
    "ident": { "column": "ident", "dataType": "VarChar" },
    "name": { "column": "name", "dataType": "VarChar" },
    "region": { "column": "province", "dataType": "Char" },
    "latitude": { "column": "latitude", "dataType": "Double" },
    "longitude": { "column": "longitude", "dataType": "Double" }
  }
}
ident name province latitude longitude
CJS9 Lac Du Bonnet (North) Seaplane Base CA-MB 50.283298 -96
CRF6 Quamichan Lake (Raven Field) Seaplane Base CA-BC 48.8083 -123.650001
CCW6 Clearwater Lake Seaplane Base CA-ON 44.8018 -79.242
CDU4 Springdale/Davis Pond Seaplane Base CA-NL 49.550052 -56.064591
CEZ5 Whitehorse Seaplane Base CA-YT 60.691101 -135.037003
CSC6 Amos (Lac Figuery) Seaplane Base CA-QC 48.499699 -78.117798

Null rows

{
  "type": "Airport",
  "countries": [{ "country": "us" }],
  "types": ["LargeAirport"],
  "nullPercentageMin": 20,
  "nullPercentageMax": 20,
  "map": {
    "iataCode": { "column": "home_airport", "dataType": "Char" },
    "municipality": { "column": "city", "dataType": "VarChar" }
  }
}
home_airport city
ORD Chicago
ONT Ontario
MCI Kansas City
SYR Syracuse
PHL Philadelphia

Every mapped column is empty on a null row, so a row never has a city without an airport.