# 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:
```bash
pip install airports-py
```
## Airport Data Structure
Each airport object contains the following fields:
```python
{
"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
```python
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.
```python
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.
```python
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).
```python
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.
```python
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.
```python
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.
```python
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.
```python
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.
```python
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.
```python
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.
```python
# 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).
```python
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.
```python
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.
```python
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
```python
# 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
```python
# Calculate distance between Singapore and London
distance = airport_data.calculate_distance('SIN', 'LHR')
print(f"Distance: {round(distance)} km")
```
### Build an airport search interface
```python
# 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
```python
# 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:
```bash
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:
1. Navigate to the root of the project:
```bash
cd path_to_airports-py
```
2. Run the tests using:
```bash
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](https://en.wikipedia.org/wiki/Chennai_International_Airport)|
| Official Website | [Chennai Airport](http://chennaiairport.com) |
| Location ID | 12513629 |
| Phone Number | 044-2340551 |
| Runway Length (in meters) | 10050 |
| Flightradar24 | [Flightradar24](https://www.flightradar24.com/airport/MAA)|
| Radarbox | [Radarbox](https://www.radarbox.com/airport/VOMM) |
| Flightaware Link | [Flightaware](https://www.flightaware.com/live/airport/VOMM)|
### 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](https://en.wikipedia.org/wiki/Singapore_Changi_Airport)|
| Official Website | [Changi Airport](http://www.changiairport.com/) |
| Location ID | 12517525 |
| Phone Number | (65) 6542 1122 |
| Runway Length (in meters) | 13200 |
| Flightradar24 | [Flightradar24](https://www.flightradar24.com/airport/SIN)|
| Radarbox | [Radarbox](https://www.radarbox.com/airport/WSSS) |
| Flightaware | [Flightaware](https://www.flightaware.com/live/airport/WSSS)|
## 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
1. **Clone the repository:**
```bash
git clone https://github.com/aashishvanand/airports-py.git
```
2. **Change into the cloned directory:**
```bash
cd airports-py
```
3. **Create a virtual environment (recommended):**
```bash
python3 -m venv venv
```
4. **Activate the virtual environment:**
```bash
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate
```
5. **Install development dependencies:**
```bash
pip install --upgrade pip
pip install build twine pytest pytest-cov
```
6. **Install the package in development mode:**
```bash
pip install -e .
```
7. **Generate the compressed data file (if needed):**
```bash
# 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
8. **Run all tests:**
```bash
python -m unittest discover tests -v
```
9. **Run tests with pytest (alternative):**
```bash
python -m pytest tests/ -v
```
10. **Run tests with coverage:**
```bash
python -m pytest tests/ -v --cov=airports --cov-report=term-missing
```
11. **Test basic functionality manually:**
```bash
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
12. **Build the package:**
```bash
# Clean previous builds
rm -rf build/ dist/ *.egg-info/
# Build package
python -m build
```
13. **Validate the package:**
```bash
twine check dist/*
```
14. **Test package installation:**
```bash
pip install dist/airports_py-*.whl --force-reinstall
```
### Development Scripts
The project includes utility scripts in the `scripts/` directory:
#### Generate Compressed Data File
```bash
# 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:
```bash
# 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:
```bash
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
1. **Update the source JSON file:**
```bash
# Edit airports/data/airports.json with new airport data
```
2. **Regenerate the compressed file:**
```bash
python scripts/generate_airports_gz.py
```
3. **Verify the update:**
```bash
python scripts/generate_airports_gz.py --verify-only
python -c "from airports import airport_data; print(f'Loaded {len(airport_data.airports)} airports')"
```
4. **Run tests to ensure compatibility:**
```bash
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](LICENSE) file for details.
## Contributing
Contributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://github.com/aashishvanand/airports-py/issues).
Raw data
{
"_id": null,
"home_page": "https://aashishvanand.me/airport-data-js/",
"name": "airports-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "airport, iata, icao, data, library, aviation, travel, geography, lookup, codes, continent, city, country, flightradar24, radarbox, flightaware, distance, coordinates, timezone, search, autocomplete, filtering, geospatial, proximity, navigation",
"author": "Aashish Vivekanand",
"author_email": "aashishvanand@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7f/f2/ea21b2236bd0aa637f763b5f1b667e60fb0a86a8e30aed7f4ad9670fa83f/airports_py-2.0.0.tar.gz",
"platform": null,
"description": "# airports-py\n\nA 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.\n\n## Features\n\n- \ud83c\udf0d **Comprehensive airport database** with worldwide coverage\n- \ud83d\udd0d **Search by IATA codes, ICAO codes, country, continent, and more**\n- \ud83d\udccd **Geographic proximity search** with customizable radius\n- \ud83d\udd17 **External links** to Wikipedia, airport websites, and flight tracking services\n- \ud83d\udccf **Distance calculation** between airports\n- \ud83c\udff7\ufe0f **Filter by airport type** (large_airport, medium_airport, small_airport, heliport, seaplane_base)\n- \ud83d\udd52 **Timezone-based airport lookup**\n- \ud83d\udca1 **Autocomplete suggestions** for search interfaces\n- \ud83c\udfaf **Advanced multi-criteria filtering**\n- **Built-in error handling** for invalid input formats\n- **Efficiently packaged** with gzipped data\n\n## Installation\n\nYou can install `airports-py` using pip:\n\n```bash\npip install airports-py\n```\n\n## Airport Data Structure\n\nEach airport object contains the following fields:\n\n```python\n{\n \"iata\": \"SIN\", # 3-letter IATA code\n \"icao\": \"WSSS\", # 4-letter ICAO code\n \"time\": \"Asia/Singapore\", # Timezone identifier\n \"country_code\": \"SG\", # 2-letter country code\n \"continent\": \"AS\", # 2-letter continent code (AS, EU, NA, SA, AF, OC, AN)\n \"airport\": \"Singapore Changi Airport\", # Airport name\n \"latitude\": \"1.35019\", # Latitude coordinate\n \"longitude\": \"103.994003\", # Longitude coordinate\n \"elevation\": \"22\", # Elevation in feet\n \"type\": \"large_airport\", # Airport type\n \"scheduled_service\": \"yes\", # Has scheduled commercial service\n \"wikipedia\": \"https://en.wikipedia.org/wiki/Singapore_Changi_Airport\",\n \"website\": \"https://www.changiairport.com\",\n \"runway_length\": \"13200\", # Longest runway in feet\n \"flightradar24_url\": \"https://www.flightradar24.com/airport/SIN\",\n \"radarbox_url\": \"https://www.radarbox.com/airport/WSSS\",\n \"flightaware_url\": \"https://www.flightaware.com/live/airport/WSSS\"\n}\n```\n\n## Basic Usage\n\n```python\nfrom airports import airport_data\n\n# Get airport by IATA code\nairport_by_iata = airport_data.get_airport_by_iata(\"SIN\")\nprint(airport_by_iata[0][\"airport\"]) # \"Singapore Changi Airport\"\n\n# Get airport by ICAO code\nairport_by_icao = airport_data.get_airport_by_icao(\"WSSS\")\nprint(airport_by_icao[0][\"country_code\"]) # \"SG\"\n\n# Search airports by name\nairports = airport_data.search_by_name(\"Singapore\")\nprint(len(airports)) # Multiple airports matching \"Singapore\"\n\n# Find nearby airports (within 50km of coordinates)\nnearby = airport_data.find_nearby_airports(1.35019, 103.994003, 50)\nprint(nearby) # Airports near Singapore Changi\n```\n\n## API Reference\n\n### Core Search Functions\n\n#### `get_airport_by_iata(iata_code)`\nFinds airports by their 3-letter IATA code.\n\n```python\nairports = airport_data.get_airport_by_iata('LHR')\n# Returns list of airports with IATA code 'LHR'\n```\n\n#### `get_airport_by_icao(icao_code)`\nFinds airports by their 4-character ICAO code.\n\n```python\nairports = airport_data.get_airport_by_icao('EGLL')\n# Returns list of airports with ICAO code 'EGLL'\n```\n\n#### `search_by_name(query)`\nSearches for airports by name (case-insensitive, minimum 2 characters).\n\n```python\nairports = airport_data.search_by_name('Heathrow')\n# Returns airports with 'Heathrow' in their name\n```\n\n### Geographic Functions\n\n#### `find_nearby_airports(lat, lon, radius_km=100)`\nFinds airports within a specified radius of given coordinates.\n\n```python\nnearby = airport_data.find_nearby_airports(51.5074, -0.1278, 100)\n# Returns airports within 100km of London coordinates\n```\n\n#### `calculate_distance(code1, code2)`\nCalculates the great-circle distance between two airports using IATA or ICAO codes.\n\n```python\ndistance = airport_data.calculate_distance('LHR', 'JFK')\n# Returns distance in kilometers (approximately 5540)\n```\n\n### Filtering Functions\n\n#### `get_airport_by_country_code(country_code)`\nFinds all airports in a specific country.\n\n```python\nus_airports = airport_data.get_airport_by_country_code('US')\n# Returns all airports in the United States\n```\n\n#### `get_airport_by_continent(continent_code)`\nFinds all airports on a specific continent.\n\n```python\nasian_airports = airport_data.get_airport_by_continent('AS')\n# Returns all airports in Asia\n# Continent codes: AS, EU, NA, SA, AF, OC, AN\n```\n\n#### `get_airports_by_type(airport_type)`\nFinds airports by their type.\n\n```python\nlarge_airports = airport_data.get_airports_by_type('large_airport')\n# Available types: large_airport, medium_airport, small_airport, heliport, seaplane_base\n\n# Convenience search for all airports\nall_airports = airport_data.get_airports_by_type('airport')\n# Returns large_airport, medium_airport, and small_airport\n```\n\n#### `get_airports_by_timezone(timezone)`\nFinds all airports within a specific timezone.\n\n```python\nlondon_airports = airport_data.get_airports_by_timezone('Europe/London')\n# Returns airports in London timezone\n```\n\n### Advanced Functions\n\n#### `find_airports(filters)`\nFinds airports matching multiple criteria.\n\n```python\n# Find large airports in Great Britain with scheduled service\nairports = airport_data.find_airports({\n 'country_code': 'GB',\n 'type': 'large_airport',\n 'has_scheduled_service': True\n})\n\n# Find airports with minimum runway length\nlong_runway_airports = airport_data.find_airports({\n 'min_runway_ft': 10000\n})\n```\n\n#### `get_autocomplete_suggestions(query, limit=10)`\nProvides autocomplete suggestions for search interfaces (returns max 10 results by default).\n\n```python\nsuggestions = airport_data.get_autocomplete_suggestions('Lon')\n# Returns up to 10 airports matching 'Lon' in name or IATA code\n```\n\n#### `get_airport_links(code)`\nGets external links for an airport using IATA or ICAO code.\n\n```python\nlinks = airport_data.get_airport_links('SIN')\n# Returns:\n# {\n# 'website': \"https://www.changiairport.com\",\n# 'wikipedia': \"https://en.wikipedia.org/wiki/Singapore_Changi_Airport\",\n# 'flightradar24': \"https://www.flightradar24.com/airport/SIN\",\n# 'radarbox': \"https://www.radarbox.com/airport/WSSS\",\n# 'flightaware': \"https://www.flightaware.com/live/airport/WSSS\"\n# }\n```\n\n## Error Handling\n\nAll functions raise appropriate exceptions for invalid input or when no data is found.\n\n```python\ntry:\n airport = airport_data.get_airport_by_iata('XYZ')\nexcept ValueError as e:\n print(e) # \"No data found for IATA code: XYZ\"\n```\n\n## Examples\n\n### Find airports near a city\n\n```python\n# Find airports within 100km of Paris\nparis_airports = airport_data.find_nearby_airports(48.8566, 2.3522, 100)\nprint(f\"Found {len(paris_airports)} airports near Paris\")\n```\n\n### Get flight distance\n\n```python\n# Calculate distance between Singapore and London\ndistance = airport_data.calculate_distance('SIN', 'LHR')\nprint(f\"Distance: {round(distance)} km\")\n```\n\n### Build an airport search interface\n\n```python\n# Get autocomplete suggestions\nsuggestions = airport_data.get_autocomplete_suggestions('New York')\nfor airport in suggestions:\n print(f\"{airport['iata']} - {airport['airport']}\")\n```\n\n### Filter airports by multiple criteria\n\n```python\n# Find large airports in Asia with scheduled service\nasian_hubs = airport_data.find_airports({\n 'continent': 'AS',\n 'type': 'large_airport',\n 'has_scheduled_service': True\n})\n```\n\n### Using Command-Line Interface (CLI)\n\nYou can also directly execute Python code from the CLI without entering the interactive shell. Navigate to the root of your project and run:\n\n```bash\npython3 -c \"from airports import airport_data; result = airport_data.get_airport_by_iata('MAA'); print(result)\"\n```\n\nReplace `'MAA'` with other codes as needed.\n\n## Testing\n\nTo test the library locally:\n\n1. Navigate to the root of the project:\n\n```bash\ncd path_to_airports-py\n```\n\n2. Run the tests using:\n\n```bash\npython3 -m unittest discover tests -v\n```\n\nThis command will discover and run all test files inside the `tests` directory and provide a detailed output.\n\n## Example Data Fields\n\nFor Chennai International Airport:\n\n| Field Name | Data |\n|----------------------|----------------------------------------------------------|\n| IATA | MAA |\n| ICAO | VOMM |\n| Time Zone | Asia/Kolkata |\n| City Code | MAA |\n| Country Code | IN |\n| Name | Chennai International Airport |\n| Latitude | 12.99 |\n| Longitude | 80.1693 |\n| Altitude (in feet) | 52 |\n| State | Tamil Nadu |\n| City | Pallavaram |\n| County | Kancheepuram |\n| State Code | Tamil Nadu |\n| Airport Type | large_airport |\n| Continent | AS |\n| State Abbreviation | IN-TN |\n| International | TRUE |\n| Wikipedia Link | [Wikipedia](https://en.wikipedia.org/wiki/Chennai_International_Airport)|\n| Official Website | [Chennai Airport](http://chennaiairport.com) |\n| Location ID | 12513629 |\n| Phone Number | 044-2340551 |\n| Runway Length (in meters) | 10050 |\n| Flightradar24 | [Flightradar24](https://www.flightradar24.com/airport/MAA)|\n| Radarbox | [Radarbox](https://www.radarbox.com/airport/VOMM) |\n| Flightaware Link | [Flightaware](https://www.flightaware.com/live/airport/VOMM)|\n\n### Singapore Changi Airport:\n\n| Field Name | Data |\n|----------------------|----------------------------------------------------------|\n| IATA | SIN |\n| ICAO | WSSS |\n| Time Zone | Asia/Singapore |\n| City Code | SIN |\n| Country Code | SG |\n| Name | Singapore Changi Airport |\n| Latitude | 1.35019 |\n| Longitude | 103.994 |\n| Altitude (in feet) | 22 |\n| State | Singapore |\n| City | Singapore |\n| County | Singapore |\n| State Code | South East |\n| Airport Type | large_airport |\n| Continent | AS |\n| State Abbreviation | SG-04 |\n| International | TRUE |\n| Wikipedia Link | [Wikipedia](https://en.wikipedia.org/wiki/Singapore_Changi_Airport)|\n| Official Website | [Changi Airport](http://www.changiairport.com/) |\n| Location ID | 12517525 |\n| Phone Number | (65) 6542 1122 |\n| Runway Length (in meters) | 13200 |\n| Flightradar24 | [Flightradar24](https://www.flightradar24.com/airport/SIN)|\n| Radarbox | [Radarbox](https://www.radarbox.com/airport/WSSS) |\n| Flightaware | [Flightaware](https://www.flightaware.com/live/airport/WSSS)|\n\n## Changelog\n\n### Version 2.0.0 (Latest)\n\n#### \ud83c\udd95 New Features\n- **`get_airports_by_timezone(timezone)`** - Find airports by timezone\n- **`get_airport_links(code)`** - Get external links for airports\n- **`find_airports(filters)`** - Advanced multi-criteria filtering\n- **`get_autocomplete_suggestions(query)`** - Autocomplete functionality\n- **Enhanced `get_airports_by_type(type)`** - Now supports convenience search for \"airport\" type\n- **`search_by_name(query)`** - Search airports by name\n- **`find_nearby_airports(lat, lon, radius_km)`** - Geographic proximity search\n- **`calculate_distance(code1, code2)`** - Distance calculation between airports\n- **External links support** - Wikipedia, websites, and flight tracking URLs\n- **Timezone information** - Complete timezone data for all airports\n- **Runway length data** - Airport runway information included\n- **Scheduled service indicator** - Whether airports have commercial scheduled service\n\n#### \ud83d\udd04 Improvements\n- Better error handling and validation with specific error messages\n- More comprehensive airport data structure\n- Improved type filtering with partial matching\n- Enhanced geographic calculations using great-circle distance\n- Case-insensitive search improvements\n- Comprehensive test coverage for all functions\n\n#### \u274c Removed from v1.x\n- Legacy simple filtering (replaced with advanced `find_airports` function)\n- Basic airport objects (expanded to include more fields)\n\n## Running the Project Locally\n\n### Prerequisites\n- Python 3.6 or higher\n- Git\n\n### Setup Instructions\n\n1. **Clone the repository:**\n```bash\ngit clone https://github.com/aashishvanand/airports-py.git\n```\n\n2. **Change into the cloned directory:**\n```bash\ncd airports-py\n```\n\n3. **Create a virtual environment (recommended):**\n```bash\npython3 -m venv venv\n```\n\n4. **Activate the virtual environment:**\n```bash\n# On macOS/Linux:\nsource venv/bin/activate\n\n# On Windows:\nvenv\\Scripts\\activate\n```\n\n5. **Install development dependencies:**\n```bash\npip install --upgrade pip\npip install build twine pytest pytest-cov\n```\n\n6. **Install the package in development mode:**\n```bash\npip install -e .\n```\n\n7. **Generate the compressed data file (if needed):**\n```bash\n# Generate airports.gz from airports.json\npython scripts/generate_airports_gz.py\n\n# Verify the data file\npython scripts/generate_airports_gz.py --verify-only\n```\n\n### Testing\n\n8. **Run all tests:**\n```bash\npython -m unittest discover tests -v\n```\n\n9. **Run tests with pytest (alternative):**\n```bash\npython -m pytest tests/ -v\n```\n\n10. **Run tests with coverage:**\n```bash\npython -m pytest tests/ -v --cov=airports --cov-report=term-missing\n```\n\n11. **Test basic functionality manually:**\n```bash\npython -c \"\nfrom airports import airport_data\nprint('Testing IATA lookup:')\nresult = airport_data.get_airport_by_iata('LHR')\nprint(f'Found: {result[0][\\\"airport\\\"]}')\nprint('\u2705 Basic functionality working!')\n\"\n```\n\n### Building and Validation\n\n12. **Build the package:**\n```bash\n# Clean previous builds\nrm -rf build/ dist/ *.egg-info/\n\n# Build package\npython -m build\n```\n\n13. **Validate the package:**\n```bash\ntwine check dist/*\n```\n\n14. **Test package installation:**\n```bash\npip install dist/airports_py-*.whl --force-reinstall\n```\n\n### Development Scripts\n\nThe project includes utility scripts in the `scripts/` directory:\n\n#### Generate Compressed Data File\n```bash\n# Generate airports.gz from airports.json\npython scripts/generate_airports_gz.py\n\n# Generate with custom compression level\npython scripts/generate_airports_gz.py --compression 6\n\n# Generate with custom source/output files\npython scripts/generate_airports_gz.py --source custom_data.json --output custom_data.gz\n\n# Verify existing compressed file\npython scripts/generate_airports_gz.py --verify-only\n```\n\n### Quick Development Workflow\n\nFor ongoing development, use this workflow:\n\n```bash\n# 1. Make your changes to the code\n\n# 2. Regenerate data file if JSON was updated\npython scripts/generate_airports_gz.py\n\n# 3. Run tests\npython -m pytest tests/ -v\n\n# 4. Build and validate\npython -m build && twine check dist/*\n\n# 5. Test installation\npip install dist/airports_py-*.whl --force-reinstall\n```\n\n### Troubleshooting\n\n**If you get import errors:**\n- Ensure you're in the virtual environment: `which python` should show the venv path\n- Verify the package is installed: `pip list | grep airports`\n- Check import works: `python -c \"import airports.airport_data\"`\n\n**If data file is missing:**\n- Generate it: `python scripts/generate_airports_gz.py`\n- Verify location: `ls -la airports/data/airports.gz`\n- Check file integrity: `python scripts/generate_airports_gz.py --verify-only`\n\n**If tests fail:**\n- Ensure data file exists and is valid\n- Check that all dependencies are installed: `pip install pytest pytest-cov`\n- Run individual tests: `python -m pytest tests/test_airport_data.py::TestAirportData::test_get_airport_by_iata -v`\n\n**If build fails:**\n- Ensure `setup.py` has correct package data configuration\n- Check that `airports/data/airports.gz` exists and is included in package\n\n### Deactivating Environment\n\nWhen you're done developing:\n```bash\ndeactivate\n```\n\n## Data Management\n\nThe airport data is stored in `airports/data/` directory:\n- `airports.json` - Source data in JSON format (4.7MB)\n- `airports.gz` - Compressed data used by the library (617KB, 86.9% compression)\n\n### Updating Airport Data\n\n1. **Update the source JSON file:**\n```bash\n# Edit airports/data/airports.json with new airport data\n```\n\n2. **Regenerate the compressed file:**\n```bash\npython scripts/generate_airports_gz.py\n```\n\n3. **Verify the update:**\n```bash\npython scripts/generate_airports_gz.py --verify-only\npython -c \"from airports import airport_data; print(f'Loaded {len(airport_data.airports)} airports')\"\n```\n\n4. **Run tests to ensure compatibility:**\n```bash\npython -m pytest tests/ -v\n```\n\n## Data Source\n\nThis library uses a comprehensive dataset of worldwide airports with regular updates to ensure accuracy and completeness.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://github.com/aashishvanand/airports-py/issues).\n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive library providing easy retrieval of airport data based on IATA, ICAO, city codes, country codes, and continents. Features geographic search, distance calculation, timezone lookup, and external links integration.",
"version": "2.0.0",
"project_urls": {
"Bug Reports": "https://github.com/aashishvanand/airports-py/issues",
"Documentation": "https://github.com/aashishvanand/airports-py#readme",
"Homepage": "https://aashishvanand.me/airport-data-js/",
"Source Code": "https://github.com/aashishvanand/airports-py"
},
"split_keywords": [
"airport",
" iata",
" icao",
" data",
" library",
" aviation",
" travel",
" geography",
" lookup",
" codes",
" continent",
" city",
" country",
" flightradar24",
" radarbox",
" flightaware",
" distance",
" coordinates",
" timezone",
" search",
" autocomplete",
" filtering",
" geospatial",
" proximity",
" navigation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e72492c11288d76f1317e32bedd04d2ade2ac721ccee17676546583732022c9e",
"md5": "a8c39acce53a1e5356503cffc2b60462",
"sha256": "f71bb9820da915e135636354d380135ad858a3715fd1ec37832a3c30a61c33d8"
},
"downloads": -1,
"filename": "airports_py-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8c39acce53a1e5356503cffc2b60462",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 1274695,
"upload_time": "2025-07-25T12:30:29",
"upload_time_iso_8601": "2025-07-25T12:30:29.817440Z",
"url": "https://files.pythonhosted.org/packages/e7/24/92c11288d76f1317e32bedd04d2ade2ac721ccee17676546583732022c9e/airports_py-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7ff2ea21b2236bd0aa637f763b5f1b667e60fb0a86a8e30aed7f4ad9670fa83f",
"md5": "dffb108b6365ae916b7041a60a1e5abf",
"sha256": "122e85733da33b09034d22b300638956272b3f94e29f45731880a40c81635f7f"
},
"downloads": -1,
"filename": "airports_py-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "dffb108b6365ae916b7041a60a1e5abf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 1257043,
"upload_time": "2025-07-25T12:30:31",
"upload_time_iso_8601": "2025-07-25T12:30:31.510705Z",
"url": "https://files.pythonhosted.org/packages/7f/f2/ea21b2236bd0aa637f763b5f1b667e60fb0a86a8e30aed7f4ad9670fa83f/airports_py-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 12:30:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aashishvanand",
"github_project": "airports-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "airports-py"
}
JSON
