airplanes.live ADS-B Integration
Overview
The Flight Traffic Exchanger service now supports airplanes.live as a second traffic data source alongside AirDEX. This integration provides manned aircraft ADS-B coverage via a community-fed aggregator with near-global reach, filling gaps in areas where AirDEX has no physical sensors deployed.
Implementation PR: droneup/droneup-flight-traffic-exchanger#7
Related issues:
- droneup/droneup-flight-traffic-exchanger#6 – Implementation task
- droneup/droneup-product-docs#23 – ADS-B provider selection spike
- droneup/droneup-product-docs#50 – ADS-B integration task
How It Works
Data Source
airplanes.live is a free, community-fed ADS-B aggregator. It collects real-time aircraft position data from volunteer feeders running ADS-B receivers globally and exposes it through a simple REST API.
- API:
GET /v2/point/{lat}/{lon}/{radius}– returns aircraft within a radius of a geographic point - Authentication: None required (public API)
- Rate limit: 1 request per second
- Max radius: 250 nautical miles
- Coverage: Global, density dependent on feeder distribution (excellent over populated areas)
Architecture
The airplanes.live provider runs as a parallel data source alongside AirDEX within the Flight Traffic Exchanger. Both providers stream observations into the same processor – the frontend renders all traffic generically with no awareness of the source.
┌─────────────────────┐
│ AirDEX Sensors │
│ (WebSocket) │
└──────────┬──────────┘
│
┌─────────────────────┐ ┌──────────▼──────────┐ ┌──────────────────┐
│ airplanes.live │ │ │ │ │
│ REST API │────────▶│ Processor │────────▶│ Frontend │
│ (polling) │ │ (cache + hub) │ │ (map view) │
└─────────────────────┘ └─────────────────────┘ └──────────────────┘Data Flow
- Provider polls
api.airplanes.live/v2/point/{lat}/{lon}/{radius}at a configurable interval (default: 4 seconds) - JSON response is mapped to the standard
Observationdomain model - Observations are streamed to the processor via gRPC
IngestService - Processor caches observations and broadcasts to subscribed frontend clients
- Frontend renders all observations identically – source is visible in the aircraft detail popup
Deduplication
Aircraft seen by both AirDEX and airplanes.live share the same ICAO address. The processor cache is keyed by ICAO address and keeps the most recent observation, so deduplication is automatic with no additional logic required.
Configuration
The provider is fully controlled via environment variables and is disabled by default.
| Variable | Default | Description |
|---|---|---|
AIRPLANESLIVE_ENABLED | false | Enable/disable the provider |
AIRPLANESLIVE_CENTER_LAT | 38.80 | Center latitude for geographic query |
AIRPLANESLIVE_CENTER_LON | -76.00 | Center longitude |
AIRPLANESLIVE_RADIUS_NM | 250 | Query radius in nautical miles (max 250) |
AIRPLANESLIVE_POLL_INTERVAL | 4s | How often to poll the API |
AIRPLANESLIVE_MAX_MESSAGE_AGE | 60s | Discard observations older than this |
AIRPLANESLIVE_BASE_URL | https://api.airplanes.live/v2 | API base URL (override for testing) |
Default Coverage Area
The defaults center on the Chesapeake Bay (38.80N, 76.00W) with a 250nm radius, covering the east coast corridor from Virginia Beach through Washington D.C. to New York City. This matches the expected ATOMx demo region.
Verified locally: a single poll returns approximately 170 aircraft across this corridor.
Field Mapping
The airplanes.live API returns ADS-B fields that map to the standard Observation model:
| airplanes.live | Observation | Notes |
|---|---|---|
hex | ICAOAddress | 24-bit ICAO hex code |
flight | Callsign | Whitespace-trimmed |
lat / lon | Latitude / Longitude | WGS-84; aircraft with missing position are skipped |
alt_geom or alt_baro | AltitudeFt | Geometric preferred; "ground" string sets OnGround=true |
gs | GroundSpeedKts | Ground speed in knots |
track | Heading | True track over ground |
geom_rate or baro_rate | VerticalRateFPM | Geometric preferred |
seen | Timestamp | Seconds since last message, converted to absolute time |
t | AircraftType | ICAO type code (e.g., B738, A321) |
squawk | Squawk | 4-digit transponder code |
| – | Source | Hardcoded AIRPLANESLIVE |
| – | ID | Format: airplaneslive-{hex} |
Resilience
The provider includes the same resilience patterns as the AirDEX provider:
- Circuit breaker – opens after 5 consecutive failures, resets after 30s
- Exponential backoff – on API errors, backs off from 2s up to 30s max
- Rate limiting – enforced at 60 requests/minute (1 req/s) to stay within API limits
- HTTP 429 handling – rate limit responses trigger the backoff mechanism
- Graceful shutdown – cleans up gRPC streams on context cancellation
Limitations
- Fixed query area – the provider polls a static geographic circle defined at startup. It does not dynamically adjust based on what the frontend viewport is showing. For the current demo use case this is sufficient since the demo area is known in advance.
- No authentication – airplanes.live is a free public API with no SLA or uptime guarantees. It is suitable for demo and development environments but should not be treated as a production-grade data source.
- Community-sourced data – coverage quality depends on volunteer feeder density. Urban areas have excellent coverage; remote areas may have gaps.
- No attribution differentiation – on the frontend map, airplanes.live aircraft appear identically to AirDEX aircraft. The source is only visible in the detail popup. A future enhancement could add visual differentiation.