A real-time air traffic visualization tool that combines data from ADS-B Exchange and OpenSky Network to provide a comprehensive view of aircraft movements in your local area.
This app is currently hosted at local-flight-map.sarumaj.com.
- Real-time aircraft tracking and visualization
- Interactive map interface using Folium
- Data integration from multiple sources:
- ADS-B Exchange API
- OpenSky Network API
- HexDB.io
- Fast and responsive web interface built with FastAPI
- Asynchronous data fetching for optimal performance
The application integrates data from multiple sources to provide comprehensive flight information:
- Authentication: Username and password required for some endpoints
- Endpoints:
/api/states/all
: Get all aircraft states/api/states/own
: Get aircraft states from own feeder/api/tracks/all
: Get all flight tracks
- Authentication: API key required
- Endpoints:
/v2/registration/{registration}
: Get aircraft by registration/v2/icao/{icao24}
: Get aircraft by ICAO24 address/v2/callsign/{callsign}
: Get aircraft by callsign/v2/sqk/{squawk}
: Get aircraft by squawk code/v2/mil
: Get military aircraft/v2/lat/{lat}/lon/{lon}/dist/{radius}
: Get aircraft in area
- Base URL: https://hexdb.io/
- Endpoints:
/api/v1/aircraft/icao/{icao24}
: Get aircraft information/api/v1/airport/icao/{icao24}
: Get airport information/api/v1/route/icao/{callsign}
: Get route information
from local_flight_map.api import (
ApiConfig,
AdsbExchangeClient, HexDbClient, OpenSkyClient,
Location, BBox
)
from datetime import datetime
# Initialize the API configuration
config = ApiConfig(
ads_b_exchange_api_key="your_api_key",
opensky_client_id="your_client_id",
opensky_client_secret="your_client_secret"
)
# OpenSky Network API Examples
async with OpenSkyClient(config) as opensky_client:
# Get all aircraft states
states = await opensky_client.get_states_from_opensky()
# Get states for specific aircraft
aircraft_states = await opensky_client.get_states_from_opensky(
icao24="icao24_code"
)
# Get states in a specific area
area_states = await opensky_client.get_states_from_opensky(
bbox=BBox(min_lat=40.0, max_lat=41.0, min_lon=-74.0, max_lon=-73.0)
)
# Get states from own feeder
own_states = await opensky_client.get_my_states_from_opensky(
serials=[1, 2, 3] # Optional: filter by sensor serial numbers
)
# Get flight track for specific aircraft
track = await opensky_client.get_track_by_aircraft_from_opensky(
icao24="icao24_code",
time_secs=datetime.now()
)
# ADS-B Exchange API Examples
async with AdsbExchangeClient(config) as adsbexchange_client:
# Get aircraft by registration
aircraft_by_reg = await adsbexchange_client.get_aircraft_from_adsbexchange_by_registration(
registration="N12345"
)
# Get aircraft by ICAO24 address
aircraft_by_icao = await adsbexchange_client.get_aircraft_from_adsbexchange_by_icao24(
icao24="icao24_code"
)
# Get aircraft by callsign
aircraft_by_callsign = await adsbexchange_client.get_aircraft_from_adsbexchange_by_callsign(
callsign="ABC123"
)
# Get aircraft by squawk code
aircraft_by_squawk = await adsbexchange_client.get_aircraft_from_adsbexchange_by_squawk(
squawk="7500"
)
# Get military aircraft
military_aircraft = await adsbexchange_client.get_military_aircrafts_from_adsbexchange()
# Get aircraft within range
aircraft_in_range = await adsbexchange_client.get_aircraft_from_adsbexchange_within_range(
center=Location(latitude=40.7128, longitude=-74.0060), # New York City
radius=50 # radius in nautical miles (92.6 km)
)
# HexDB API Examples
async with HexDbClient(config) as hexdb_client:
# Get aircraft information
aircraft_info = await hexdb_client.get_aircraft_information_from_hexdb(
icao24="icao24_code"
)
# Get airport information
airport_info = await hexdb_client.get_airport_information_from_hexdb(
icao24="KJFK" # ICAO airport code
)
# Get route information
route_info = await hexdb_client.get_route_information_from_hexdb(
callsign="ABC123"
)
StateVector
: Contains aircraft position, speed, altitude, and other flight data- Basic info: ICAO24, callsign, origin country
- Position: latitude, longitude, altitude (barometric and geometric)
- Performance: velocity, true track, vertical rate
- Status: on ground, squawk, special position indicator
- Source: position source (ADS-B, ASTERIX, MLAT, FLARM)
- Category: aircraft category (Light, Small, Large, Heavy, etc.)
States
: Collection of StateVector objects with timestampFlightTrack
: Contains flight path data with waypoints- Basic info: ICAO24, callsign, start/end time
- Path: list of waypoints with position and altitude data
Waypoint
: Individual position point in a flight track- Time: Unix timestamp
- Position: latitude, longitude
- Altitude: barometric altitude
- Track: true track angle
- Status: on ground flag
AircraftProperties
: Detailed aircraft information including:- Basic info: ICAO24, registration, type, callsign
- Position: latitude, longitude, altitude (barometric and geometric)
- Performance: ground speed, airspeed (indicated/true), Mach number
- Weather: wind direction/speed, outside air temperature
- Navigation: track angle, heading, rate of climb/descent
- System status: squawk, emergency status, category
- Technical: signal strength, GPS status, message count
- Navigation modes: QNH, MCP/FMS altitude, heading
- Integrity: navigation accuracy, surveillance level
AdsbExchangeResponse
: Container for aircraft data with:- List of aircraft
- API message
- Timestamps
- Processing information
AircraftInformation
: Aircraft registration and type details- Basic info: ICAO type code, manufacturer, Mode S code
- Registration: operator flag code, registered owners, registration number
- Type: aircraft type description
AirportInformation
: Airport location and identification- Codes: IATA, ICAO, country code
- Location: latitude, longitude
- Details: airport name, region name
RouteInformation
: Flight route details- Flight: flight number
- Route: route description
- Update time: timestamp of last update
All response objects support conversion to GeoJSON format for easy integration with mapping libraries.
- Python 3.12 or higher
- Internet connection for API access
- Web browser for viewing the map interface
- Clone the repository:
git clone https://github.com/sarumaj/local-flight-map.git
cd local-flight-map
- Create and activate a virtual environment:
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
- Install the package:
pip install -e .
Create a .env
file in the project root with your API credentials:
ADS_B_EXCHANGE_API_KEY=your_api_key_here
OPENSKY_USERNAME=your_username_here
OPENSKY_PASSWORD=your_password_here
- Start the application:
local-flight-map
-
Open your web browser and navigate to
http://localhost:5006
-
The interactive map will display:
- Current aircraft positions and path tracking
- Aircraft information on hover
- Real-time updates
To run tests:
pip install -e ".[test]"
pytest
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.