airports-py

A comprehensive Python library providing easy retrieval of airport data based on IATA, ICAO, city codes, country codes, and continents. Ideal for developers building applications related to aviation, travel, and geography in Python.

Features

🌍 Comprehensive airport database with worldwide coverage
🔍 Search by IATA codes, ICAO codes, country, continent, and more
📍 Geographic proximity search with customizable radius
🔗 External links to Wikipedia, airport websites, and flight tracking services
📏 Distance calculation between airports
🏷️ Filter by airport type (large_airport, medium_airport, small_airport, heliport, seaplane_base)
🕒 Timezone-based airport lookup
💡 Autocomplete suggestions for search interfaces
🎯 Advanced multi-criteria filtering
Built-in error handling for invalid input formats
Efficiently packaged with gzipped data

Installation

You can install airports-py using pip:

pip install airports-py

Airport Data Structure

Each airport object contains the following fields:

{
    "iata": "SIN",                    # 3-letter IATA code
    "icao": "WSSS",                   # 4-letter ICAO code
    "time": "Asia/Singapore",         # Timezone identifier
    "country_code": "SG",             # 2-letter country code
    "continent": "AS",                # 2-letter continent code (AS, EU, NA, SA, AF, OC, AN)
    "airport": "Singapore Changi Airport",  # Airport name
    "latitude": "1.35019",            # Latitude coordinate
    "longitude": "103.994003",        # Longitude coordinate
    "elevation": "22",                # Elevation in feet
    "type": "large_airport",          # Airport type
    "scheduled_service": "yes",       # Has scheduled commercial service
    "wikipedia": "https://en.wikipedia.org/wiki/Singapore_Changi_Airport",
    "website": "https://www.changiairport.com",
    "runway_length": "13200",         # Longest runway in feet
    "flightradar24_url": "https://www.flightradar24.com/airport/SIN",
    "radarbox_url": "https://www.radarbox.com/airport/WSSS",
    "flightaware_url": "https://www.flightaware.com/live/airport/WSSS"
}

Basic Usage

from airports import airport_data

# Get airport by IATA code
airport_by_iata = airport_data.get_airport_by_iata("SIN")
print(airport_by_iata[0]["airport"])  # "Singapore Changi Airport"

# Get airport by ICAO code
airport_by_icao = airport_data.get_airport_by_icao("WSSS")
print(airport_by_icao[0]["country_code"])  # "SG"

# Search airports by name
airports = airport_data.search_by_name("Singapore")
print(len(airports))  # Multiple airports matching "Singapore"

# Find nearby airports (within 50km of coordinates)
nearby = airport_data.find_nearby_airports(1.35019, 103.994003, 50)
print(nearby)  # Airports near Singapore Changi

API Reference

Core Search Functions

`get_airport_by_iata(iata_code)`

Finds airports by their 3-letter IATA code.

airports = airport_data.get_airport_by_iata('LHR')
# Returns list of airports with IATA code 'LHR'

`get_airport_by_icao(icao_code)`

Finds airports by their 4-character ICAO code.

airports = airport_data.get_airport_by_icao('EGLL')
# Returns list of airports with ICAO code 'EGLL'

`search_by_name(query)`

Searches for airports by name (case-insensitive, minimum 2 characters).

airports = airport_data.search_by_name('Heathrow')
# Returns airports with 'Heathrow' in their name

Geographic Functions

`find_nearby_airports(lat, lon, radius_km=100)`

Finds airports within a specified radius of given coordinates.

nearby = airport_data.find_nearby_airports(51.5074, -0.1278, 100)
# Returns airports within 100km of London coordinates

`calculate_distance(code1, code2)`

Calculates the great-circle distance between two airports using IATA or ICAO codes.

distance = airport_data.calculate_distance('LHR', 'JFK')
# Returns distance in kilometers (approximately 5540)

Filtering Functions

`get_airport_by_country_code(country_code)`

Finds all airports in a specific country.

us_airports = airport_data.get_airport_by_country_code('US')
# Returns all airports in the United States

`get_airport_by_continent(continent_code)`

Finds all airports on a specific continent.

asian_airports = airport_data.get_airport_by_continent('AS')
# Returns all airports in Asia
# Continent codes: AS, EU, NA, SA, AF, OC, AN

`get_airports_by_type(airport_type)`

Finds airports by their type.

large_airports = airport_data.get_airports_by_type('large_airport')
# Available types: large_airport, medium_airport, small_airport, heliport, seaplane_base

# Convenience search for all airports
all_airports = airport_data.get_airports_by_type('airport')
# Returns large_airport, medium_airport, and small_airport

`get_airports_by_timezone(timezone)`

Finds all airports within a specific timezone.

london_airports = airport_data.get_airports_by_timezone('Europe/London')
# Returns airports in London timezone

Advanced Functions

`find_airports(filters)`

Finds airports matching multiple criteria.

# Find large airports in Great Britain with scheduled service
airports = airport_data.find_airports({
    'country_code': 'GB',
    'type': 'large_airport',
    'has_scheduled_service': True
})

# Find airports with minimum runway length
long_runway_airports = airport_data.find_airports({
    'min_runway_ft': 10000
})

`get_autocomplete_suggestions(query, limit=10)`

Provides autocomplete suggestions for search interfaces (returns max 10 results by default).

suggestions = airport_data.get_autocomplete_suggestions('Lon')
# Returns up to 10 airports matching 'Lon' in name or IATA code

`get_airport_links(code)`

Gets external links for an airport using IATA or ICAO code.

links = airport_data.get_airport_links('SIN')
# Returns:
# {
#     'website': "https://www.changiairport.com",
#     'wikipedia': "https://en.wikipedia.org/wiki/Singapore_Changi_Airport",
#     'flightradar24': "https://www.flightradar24.com/airport/SIN",
#     'radarbox': "https://www.radarbox.com/airport/WSSS",
#     'flightaware': "https://www.flightaware.com/live/airport/WSSS"
# }

Error Handling

All functions raise appropriate exceptions for invalid input or when no data is found.

try:
    airport = airport_data.get_airport_by_iata('XYZ')
except ValueError as e:
    print(e)  # "No data found for IATA code: XYZ"

Examples

Find airports near a city

# Find airports within 100km of Paris
paris_airports = airport_data.find_nearby_airports(48.8566, 2.3522, 100)
print(f"Found {len(paris_airports)} airports near Paris")

Get flight distance

# Calculate distance between Singapore and London
distance = airport_data.calculate_distance('SIN', 'LHR')
print(f"Distance: {round(distance)} km")

Build an airport search interface

# Get autocomplete suggestions
suggestions = airport_data.get_autocomplete_suggestions('New York')
for airport in suggestions:
    print(f"{airport['iata']} - {airport['airport']}")

Filter airports by multiple criteria

# Find large airports in Asia with scheduled service
asian_hubs = airport_data.find_airports({
    'continent': 'AS',
    'type': 'large_airport',
    'has_scheduled_service': True
})

Using Command-Line Interface (CLI)

You can also directly execute Python code from the CLI without entering the interactive shell. Navigate to the root of your project and run:

python3 -c "from airports import airport_data; result = airport_data.get_airport_by_iata('MAA'); print(result)"

Replace 'MAA' with other codes as needed.

Testing

To test the library locally:

Navigate to the root of the project:

cd path_to_airports-py

Run the tests using:

python3 -m unittest discover tests -v

This command will discover and run all test files inside the tests directory and provide a detailed output.

Example Data Fields

For Chennai International Airport:

Field Name	Data
IATA	MAA
ICAO	VOMM
Time Zone	Asia/Kolkata
City Code	MAA
Country Code	IN
Name	Chennai International Airport
Latitude	12.99
Longitude	80.1693
Altitude (in feet)	52
State	Tamil Nadu
City	Pallavaram
County	Kancheepuram
State Code	Tamil Nadu
Airport Type	large_airport
Continent	AS
State Abbreviation	IN-TN
International	TRUE
Wikipedia Link	Wikipedia
Official Website	Chennai Airport
Location ID	12513629
Phone Number	044-2340551
Runway Length (in meters)	10050
Flightradar24	Flightradar24
Radarbox	Radarbox
Flightaware Link	Flightaware

Singapore Changi Airport:

Field Name	Data
IATA	SIN
ICAO	WSSS
Time Zone	Asia/Singapore
City Code	SIN
Country Code	SG
Name	Singapore Changi Airport
Latitude	1.35019
Longitude	103.994
Altitude (in feet)	22
State	Singapore
City	Singapore
County	Singapore
State Code	South East
Airport Type	large_airport
Continent	AS
State Abbreviation	SG-04
International	TRUE
Wikipedia Link	Wikipedia
Official Website	Changi Airport
Location ID	12517525
Phone Number	(65) 6542 1122
Runway Length (in meters)	13200
Flightradar24	Flightradar24
Radarbox	Radarbox
Flightaware	Flightaware

Changelog

Version 2.0.0 (Latest)

🆕 New Features

get_airports_by_timezone(timezone) - Find airports by timezone
get_airport_links(code) - Get external links for airports
find_airports(filters) - Advanced multi-criteria filtering
get_autocomplete_suggestions(query) - Autocomplete functionality
Enhanced get_airports_by_type(type) - Now supports convenience search for "airport" type
search_by_name(query) - Search airports by name
find_nearby_airports(lat, lon, radius_km) - Geographic proximity search
calculate_distance(code1, code2) - Distance calculation between airports
External links support - Wikipedia, websites, and flight tracking URLs
Timezone information - Complete timezone data for all airports
Runway length data - Airport runway information included
Scheduled service indicator - Whether airports have commercial scheduled service

🔄 Improvements

Better error handling and validation with specific error messages
More comprehensive airport data structure
Improved type filtering with partial matching
Enhanced geographic calculations using great-circle distance
Case-insensitive search improvements
Comprehensive test coverage for all functions

❌ Removed from v1.x

Legacy simple filtering (replaced with advanced find_airports function)
Basic airport objects (expanded to include more fields)

Running the Project Locally

Prerequisites

Python 3.6 or higher
Git

Setup Instructions

Clone the repository:

git clone https://github.com/aashishvanand/airports-py.git

Change into the cloned directory:

cd airports-py

Create a virtual environment (recommended):

python3 -m venv venv

Activate the virtual environment:

# On macOS/Linux:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

Install development dependencies:

pip install --upgrade pip
pip install build twine pytest pytest-cov

Install the package in development mode:

pip install -e .

Generate the compressed data file (if needed):

# Generate airports.gz from airports.json
python scripts/generate_airports_gz.py

# Verify the data file
python scripts/generate_airports_gz.py --verify-only

Testing

Run all tests:

python -m unittest discover tests -v

Run tests with pytest (alternative):

python -m pytest tests/ -v

Run tests with coverage:

python -m pytest tests/ -v --cov=airports --cov-report=term-missing

Test basic functionality manually:

python -c "
from airports import airport_data
print('Testing IATA lookup:')
result = airport_data.get_airport_by_iata('LHR')
print(f'Found: {result[0][\"airport\"]}')
print('✅ Basic functionality working!')
"

Building and Validation

Build the package:

# Clean previous builds
rm -rf build/ dist/ *.egg-info/

# Build package
python -m build

Validate the package:

twine check dist/*

Test package installation:

pip install dist/airports_py-*.whl --force-reinstall

Development Scripts

The project includes utility scripts in the scripts/ directory:

Generate Compressed Data File

# Generate airports.gz from airports.json
python scripts/generate_airports_gz.py

# Generate with custom compression level
python scripts/generate_airports_gz.py --compression 6

# Generate with custom source/output files
python scripts/generate_airports_gz.py --source custom_data.json --output custom_data.gz

# Verify existing compressed file
python scripts/generate_airports_gz.py --verify-only

Quick Development Workflow

For ongoing development, use this workflow:

# 1. Make your changes to the code

# 2. Regenerate data file if JSON was updated
python scripts/generate_airports_gz.py

# 3. Run tests
python -m pytest tests/ -v

# 4. Build and validate
python -m build && twine check dist/*

# 5. Test installation
pip install dist/airports_py-*.whl --force-reinstall

Troubleshooting

If you get import errors:

Ensure you're in the virtual environment: which python should show the venv path
Verify the package is installed: pip list | grep airports
Check import works: python -c "import airports.airport_data"

If data file is missing:

Generate it: python scripts/generate_airports_gz.py
Verify location: ls -la airports/data/airports.gz
Check file integrity: python scripts/generate_airports_gz.py --verify-only

If tests fail:

Ensure data file exists and is valid
Check that all dependencies are installed: pip install pytest pytest-cov
Run individual tests: python -m pytest tests/test_airport_data.py::TestAirportData::test_get_airport_by_iata -v

If build fails:

Ensure setup.py has correct package data configuration
Check that airports/data/airports.gz exists and is included in package

Deactivating Environment

When you're done developing:

deactivate

Data Management

The airport data is stored in airports/data/ directory:

airports.json - Source data in JSON format (4.7MB)
airports.gz - Compressed data used by the library (617KB, 86.9% compression)

Updating Airport Data

Update the source JSON file:

# Edit airports/data/airports.json with new airport data

Regenerate the compressed file:

python scripts/generate_airports_gz.py

Verify the update:

python scripts/generate_airports_gz.py --verify-only
python -c "from airports import airport_data; print(f'Loaded {len(airport_data.airports)} airports')"

Run tests to ensure compatibility:

python -m pytest tests/ -v

Data Source

This library uses a comprehensive dataset of worldwide airports with regular updates to ensure accuracy and completeness.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.github/workflows		.github/workflows
airports		airports
scripts		scripts
tests		tests
.DS_Store		.DS_Store
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
requirements.txt		requirements.txt
setup.py		setup.py

License

aashishvanand/airports-py

Folders and files

Latest commit

History

Repository files navigation

airports-py

Features

Installation

Airport Data Structure

Basic Usage

API Reference

Core Search Functions

get_airport_by_iata(iata_code)

get_airport_by_icao(icao_code)

search_by_name(query)

Geographic Functions

find_nearby_airports(lat, lon, radius_km=100)

calculate_distance(code1, code2)

Filtering Functions

get_airport_by_country_code(country_code)

get_airport_by_continent(continent_code)

get_airports_by_type(airport_type)

get_airports_by_timezone(timezone)

Advanced Functions

find_airports(filters)

get_autocomplete_suggestions(query, limit=10)

get_airport_links(code)

Error Handling

Examples

Find airports near a city

Get flight distance

Build an airport search interface

Filter airports by multiple criteria

Using Command-Line Interface (CLI)

Testing

Example Data Fields

Singapore Changi Airport:

Changelog

Version 2.0.0 (Latest)

🆕 New Features

🔄 Improvements

❌ Removed from v1.x

Running the Project Locally

Prerequisites

Setup Instructions

Testing

Building and Validation

Development Scripts

Generate Compressed Data File

Quick Development Workflow

Troubleshooting

Deactivating Environment

Data Management

Updating Airport Data

Data Source

License

Contributing

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

`get_airport_by_iata(iata_code)`

`get_airport_by_icao(icao_code)`

`search_by_name(query)`

`find_nearby_airports(lat, lon, radius_km=100)`

`calculate_distance(code1, code2)`

`get_airport_by_country_code(country_code)`

`get_airport_by_continent(continent_code)`

`get_airports_by_type(airport_type)`

`get_airports_by_timezone(timezone)`

`find_airports(filters)`

`get_autocomplete_suggestions(query, limit=10)`

`get_airport_links(code)`

Packages