Skip to content

sarumaj/local-flight-map

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

42 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

release deploy GitHub Release Libraries.io dependency status for GitHub repo


Local Flight Map

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.

screenshot.png

Features

  • 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

API Documentation

Data Sources

The application integrates data from multiple sources to provide comprehensive flight information:

OpenSky Network API

  • 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

ADS-B Exchange API

  • 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

HexDB API

  • 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

API Client Usage

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"
    )

Response Objects

OpenSky Network API

  • 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 timestamp
  • FlightTrack: 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

ADS-B Exchange API

  • 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

HexDB API

  • 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.

Requirements

  • Python 3.12 or higher
  • Internet connection for API access
  • Web browser for viewing the map interface

Installation

  1. Clone the repository:
git clone https://github.com/sarumaj/local-flight-map.git
cd local-flight-map
  1. Create and activate a virtual environment:
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. Install the package:
pip install -e .

Configuration

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

Usage

  1. Start the application:
local-flight-map
  1. Open your web browser and navigate to http://localhost:5006

  2. The interactive map will display:

    • Current aircraft positions and path tracking
    • Aircraft information on hover
    • Real-time updates

Development

To run tests:

pip install -e ".[test]"
pytest

License

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

About

Open Air Traffic map based on ADS-B Exchange and Open Sky Data.

Topics

Resources

License

Stars

Watchers

Forks

Sponsor this project

  •  

Packages

No packages published