Back to Contrail
Contrail Logo Contrail API Documentation
Terms & Compliance Open Console

Contrail API Reference

Contrail is a near-real-time global aviation telemetry service and radar platform. It aggregates live ADS-B state vectors from The OpenSky Network and community sensor nodes (adsb.fi mesh), dynamically enriched with commercial airline metadata, OurAirports aerodrome references, transponder emergency triggers, and predictive diversion algorithms.

Base URL: https://airline.api.veyino.org
API Version: v1.0 — All endpoints return JSON responses with standard telemetry envelopes, pagination metadata, and provider attribution.

Authentication & Rate Limiting

All data endpoints require a registered API key. Registration is free for verified non-commercial, research, and educational uses.

Providing Your API Key

Pass your API key in every request using either the X-API-Key HTTP header (recommended) or the api_key query parameter:

# Method 1: HTTP Header (Recommended) curl -H "X-API-Key: ct_live_your_api_key_here" "https://airline.api.veyino.org/api/v1/flights?limit=5" # Method 2: Query Parameter curl "https://airline.api.veyino.org/api/v1/flights?api_key=ct_live_your_api_key_here&limit=5"

Default Rate Limits

MetricAllowanceScopeEnforcement Action
Requests per Minute (RPM)60 req/minPer API KeyHTTP 429 Too Many Requests, Retry-After header
Requests per Hour (RPH)1,000 req/hrPer API KeyHTTP 429 Too Many Requests
Daily Quota10,000 req/dayPer AccountHTTP 429 Rate Limit Exceeded

Requests exceeding limits trigger automated email warnings. Continued aggressive flooding may result in key revocation.

Attribution & License Notice

Contrail is licensed strictly for Non-Commercial Use Only. Every API response includes a top-level attribution object acknowledging upstream providers:

{ "api_version": "v1.0", "base_url": "https://airline.api.veyino.org", "attribution": { "notice": "Strictly Non-Commercial Use Only. Contrail collects and redistributes data as-is...", "sources": [ "Live aircraft positions: The OpenSky Network (https://opensky-network.org)", "Live aircraft positions: adsb.fi (https://adsb.fi)", "Flight routes: adsbdb.com — David Taylor & Jim Mason", "Aircraft registrations: adsbdb.com, PlaneBase", "Airports: OurAirports (https://ourairports.com, public domain)" ], "paper_citation": "Matthias Schäfer et al. Bringing Up OpenSky...", "data_notice_url": "https://airline.api.veyino.org/data-notice" } }

API Endpoints Reference

GET /api/v1/health

Public system health check and upstream poller telemetry status. Does not require an API key.

curl https://airline.api.veyino.org/api/v1/health
GET /api/v1/flights

Query live tracked flights with geospatial bounding box, altitude filters, callsign, and emergency status.

ParameterTypeDescription
bboxstringBounding box filter: minLat,minLon,maxLat,maxLon (e.g. 18.0,73.0,54.0,135.0 for East Asia)
callsignstringPrefix match for ICAO/IATA callsign (e.g. CSN, AAL)
hexstringExact 24-bit ICAO aircraft transponder hexadecimal code
originstringOrigin airport ICAO code (e.g. ZBAA, KJFK)
deststringDestination airport ICAO code (e.g. ZSPD, EGLL)
emergencybooleanFilter for active emergency squawks (true / 1)
divertingbooleanFilter for flights with predictive diversion warnings (true / 1)
min_alt / max_altnumberBarometric altitude boundaries in feet
limitintegerResults per page (1 to 3000, default: 50)
pageintegerPagination page offset (default: 1)
sortstringSort field: altitude, speed, last_seen
orderstringSort direction: asc or desc
curl -H "X-API-Key: YOUR_KEY" "https://airline.api.veyino.org/api/v1/flights?bbox=20.0,110.0,40.0,125.0&limit=100"
GET /api/v1/flights/{identifier}

Retrieve full telemetry, route details, and diversion diagnostics for a single aircraft identified by ICAO callsign or hex address.

curl -H "X-API-Key: YOUR_KEY" https://airline.api.veyino.org/api/v1/flights/CSN3104
GET /api/v1/history or /api/v1/flights/{id}/history

Retrieve historical track trajectory points up to the 90-day retention horizon.

ParameterTypeDescription
callsign / hexstringFlight callsign or hex transponder address
from / tointegerUnix timestamp epoch bounds (defaults to past 90 days)
limitintegerMaximum historical points (default: 300, max: 2000)
curl -H "X-API-Key: YOUR_KEY" "https://airline.api.veyino.org/api/v1/history?callsign=CSN3104&limit=250"
GET /api/v1/emergencies

Query aircraft actively squawking emergency transponder codes (7700 General, 7600 Radio Failure, 7500 Hijack/Unlawful Interference).

curl -H "X-API-Key: YOUR_KEY" https://airline.api.veyino.org/api/v1/emergencies
GET /api/v1/diversions

Query flights flagged by Contrail's algorithmic diversion engine based on heading deviations, premature high-rate descents, or missed approach holds.

curl -H "X-API-Key: YOUR_KEY" https://airline.api.veyino.org/api/v1/diversions
GET /api/v1/airports/{code}

Lookup aerodrome coordinates, runways, elevation, and active inbound/outbound traffic by ICAO or IATA code.

curl -H "X-API-Key: YOUR_KEY" https://airline.api.veyino.org/api/v1/airports/ZBAA
GET /api/v1/stats

Real-time global counters: total tracked aircraft, active emergencies, predicted diversions, and poller cadence.

curl -H "X-API-Key: YOUR_KEY" https://airline.api.veyino.org/api/v1/stats
POST /api/v1/query

Execute structured JSON queries with composite filter criteria and sorting.

curl -X POST -H "Content-Type: application/json" -H "X-API-Key: YOUR_KEY" \ https://airline.api.veyino.org/api/v1/query \ -d '{ "filters": { "bbox": {"min_lat": 20.0, "min_lon": 110.0, "max_lat": 40.0, "max_lon": 125.0}, "min_alt": 25000, "max_alt": 42000 }, "limit": 50, "sort_by": "altitude", "sort_order": "desc" }'

7 Core Field Groups

Contrail's flight telemetry object is organized into 7 standardized top-level blocks:

Field GroupKey FieldsDescription
flightcallsign_icao, callsign_iata, airlineCallsign identity, flight number, and operating carrier
aircrafthex, registration, type_code, countryAirframe ICAO hex, tail registration, and nationality
telemetryposition, altitude, speed, attitudeLatitude, longitude, barometric/geometric altitude, ground speed, track heading, vertical rate (fpm and mps)
routeorigin, destination, waypointsDeparture and arrival aerodromes with coordinates and planned navigation fixes
emergencyis_emergency, squawk, categoryTransponder squawk state and emergency alert classification
diversion_analysispredicted_diversion, probability_level, triggered_criteriaPredictive diversion warning score, criteria flags, and candidate diversion alternates
metadataupstream_source, last_updatedSensor network origin and UTC timestamp

HTTP Status Codes

StatusMeaningResolution
200 OKSuccessRequest completed normally
400 Bad RequestMalformed RequestCheck query parameters (e.g. malformed bbox bounds or negative limits)
401 UnauthorizedMissing / Invalid API KeyProvide a valid key via X-API-Key header or ?api_key= parameter
403 ForbiddenAccess SuspendedAccount suspended or administrator endpoint accessed without credentials
404 Not FoundResource MissingTarget flight identifier or airport code does not exist
429 Too Many RequestsRate Limit ExceededSlow down request cadence; check Retry-After header
500 Server ErrorInternal ErrorTelemetry node error; automated self-healing triggers automatically