Airports

Airport lookup and selection.

Provides geographic search, filtering by proximity, country, type, and runway requirements using the OurAirports global database.

Data source

OurAirports (https://ourairports.com), maintained by David Megginson. CSV data retrieved from https://github.com/davidmegginson/ourairports-data. Licensed under the Public Domain (CC0).

class Airport[source]

Bases: object

An airport looked up by ICAO code from the OurAirports dataset.

Lazily initializes airport data on first instantiation. Properties provide access to location, elevation, and runway information.

Parameters:

icao (str) – ICAO code of the airport (e.g., “KJFK”).

Raises:

ValueError – If the ICAO code is not found in the dataset.

__init__(icao)[source]
Parameters:

icao (str)

property longitude: float

Longitude of the airport.

property latitude: float

Latitude of the airport.

property geometry: Point

Shapely Point geometry of the airport.

property icao_code: str

ICAO code of the airport.

property iata_code: str | None

IATA code of the airport, or None if it has none.

property name: str

Name of the airport.

property country: str

ISO country code of the airport.

property municipality: str | None

Municipality of the airport, or None if not recorded.

property elevation

Elevation of the airport in meters. Returns None if not available.

property elevation_ft: float | None

Elevation of the airport in feet. Returns None if not available.

property runways: DataFrame

Runway details for this airport as a DataFrame.

airports_within_radius(lat, lon, radius, unit='kilometers', return_details=False)[source]

Find all airports within a specified radius of a given point.

Parameters:

  • lat (float) – Latitude of the center point.

  • lon (float) – Longitude of the center point.

  • radius (float) – Search radius.

  • unit (str) – Distance unit for radius (default: “kilometers”).

  • return_details (bool) – If True, return a GeoDataFrame with a ‘distance_m’ column instead of a list of ICAO codes.

Return type:

list[str] | GeoDataFrame

Returns:

List of ICAO codes, or a GeoDataFrame if return_details is True.

find_nearest_airport(lat, lon)[source]

Find the nearest airport to a given latitude and longitude.

Returns:

ICAO code of the nearest airport.

Return type:

str

Parameters:
find_nearest_airports(lat, lon, n=5)[source]

Find the N nearest airports to a given latitude and longitude.

Returns:

ICAO codes of the nearest airports, ordered by proximity.

Return type:

List[str]

Parameters:
generate_geojson(filepath='airports.geojson', icao_codes=None)[source]

Generate a GeoJSON file of the airports using GeoPandas with CRS explicitly set to EPSG:4326.

Parameters:

  • filepath (str) – Path to save the GeoJSON file. Defaults to “airports.geojson”.

  • icao_codes (Union[str, List[str]]) – List of ICAO codes to subset the GeoJSON. If None, export all airports.

Return type:

None

get_airport_details(icao_codes)[source]

Get details of airports for given ICAO code(s).

Return type:

DataFrame

Parameters:

icao_codes (str | list[str])

get_airports()[source]

Get the initialized GeoDataFrame of airports.

Return type:

GeoDataFrame

get_longest_runway(icao)[source]

Return the length in feet of the longest runway at the given airport.

Returns:

Longest runway length in feet, or None if no runway data is available.

Return type:

float

Parameters:

icao (str)

get_runway_details(icao_codes)[source]

Retrieve details of all runways for one or more airports.

Parameters:

icao_codes (Union[str, List[str]]) – A single ICAO code or a list of ICAO codes.

Returns:

A DataFrame with runway details for the given airport(s).

Return type:

pd.DataFrame

get_runways()[source]

Get the initialized DataFrame of runways.

Return type:

DataFrame

initialize_data(countries=None, min_runway_length=None, runway_surface=None, airport_types=None, cache_dir=None, refresh=False)[source]

Initialize airport and runway data with filtering options.

Downloaded CSVs are cached and never auto-refreshed; OurAirports publishes updates daily, so pass refresh=True (or delete the cached files) to pick up new data. A log hint is emitted when the cached airports.csv is older than ~30 days.

Parameters:

  • countries (list[str] | None) – ISO country codes to filter airports by.

  • min_runway_length (int | None) – Minimum runway length in feet.

  • runway_surface (str | list[str] | None) – Runway surface type(s) to filter by.

  • airport_types (list[str] | None) – Airport types to include (default: large, medium, small).

  • cache_dir (str | Path | None) – Directory to store downloaded data files. Defaults to hyplan.terrain.io.get_cache_root() (~/.cache/hyplan, overridable via the HYPLAN_CACHE_ROOT environment variable).

  • refresh (bool) – If True, re-download data files even if they already exist.

Return type:

None