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.
https://airline.api.veyino.orgAPI 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:
Default Rate Limits
| Metric | Allowance | Scope | Enforcement Action |
|---|---|---|---|
| Requests per Minute (RPM) | 60 req/min | Per API Key | HTTP 429 Too Many Requests, Retry-After header |
| Requests per Hour (RPH) | 1,000 req/hr | Per API Key | HTTP 429 Too Many Requests |
| Daily Quota | 10,000 req/day | Per Account | HTTP 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 Endpoints Reference
Public system health check and upstream poller telemetry status. Does not require an API key.
Query live tracked flights with geospatial bounding box, altitude filters, callsign, and emergency status.
| Parameter | Type | Description |
|---|---|---|
bbox | string | Bounding box filter: minLat,minLon,maxLat,maxLon (e.g. 18.0,73.0,54.0,135.0 for East Asia) |
callsign | string | Prefix match for ICAO/IATA callsign (e.g. CSN, AAL) |
hex | string | Exact 24-bit ICAO aircraft transponder hexadecimal code |
origin | string | Origin airport ICAO code (e.g. ZBAA, KJFK) |
dest | string | Destination airport ICAO code (e.g. ZSPD, EGLL) |
emergency | boolean | Filter for active emergency squawks (true / 1) |
diverting | boolean | Filter for flights with predictive diversion warnings (true / 1) |
min_alt / max_alt | number | Barometric altitude boundaries in feet |
limit | integer | Results per page (1 to 3000, default: 50) |
page | integer | Pagination page offset (default: 1) |
sort | string | Sort field: altitude, speed, last_seen |
order | string | Sort direction: asc or desc |
Retrieve full telemetry, route details, and diversion diagnostics for a single aircraft identified by ICAO callsign or hex address.
/api/v1/flights/{id}/history
Retrieve historical track trajectory points up to the 90-day retention horizon.
| Parameter | Type | Description |
|---|---|---|
callsign / hex | string | Flight callsign or hex transponder address |
from / to | integer | Unix timestamp epoch bounds (defaults to past 90 days) |
limit | integer | Maximum historical points (default: 300, max: 2000) |
Query aircraft actively squawking emergency transponder codes (7700 General, 7600 Radio Failure, 7500 Hijack/Unlawful Interference).
Query flights flagged by Contrail's algorithmic diversion engine based on heading deviations, premature high-rate descents, or missed approach holds.
Lookup aerodrome coordinates, runways, elevation, and active inbound/outbound traffic by ICAO or IATA code.
Real-time global counters: total tracked aircraft, active emergencies, predicted diversions, and poller cadence.
Execute structured JSON queries with composite filter criteria and sorting.
7 Core Field Groups
Contrail's flight telemetry object is organized into 7 standardized top-level blocks:
| Field Group | Key Fields | Description |
|---|---|---|
flight | callsign_icao, callsign_iata, airline | Callsign identity, flight number, and operating carrier |
aircraft | hex, registration, type_code, country | Airframe ICAO hex, tail registration, and nationality |
telemetry | position, altitude, speed, attitude | Latitude, longitude, barometric/geometric altitude, ground speed, track heading, vertical rate (fpm and mps) |
route | origin, destination, waypoints | Departure and arrival aerodromes with coordinates and planned navigation fixes |
emergency | is_emergency, squawk, category | Transponder squawk state and emergency alert classification |
diversion_analysis | predicted_diversion, probability_level, triggered_criteria | Predictive diversion warning score, criteria flags, and candidate diversion alternates |
metadata | upstream_source, last_updated | Sensor network origin and UTC timestamp |
HTTP Status Codes
| Status | Meaning | Resolution |
|---|---|---|
200 OK | Success | Request completed normally |
400 Bad Request | Malformed Request | Check query parameters (e.g. malformed bbox bounds or negative limits) |
401 Unauthorized | Missing / Invalid API Key | Provide a valid key via X-API-Key header or ?api_key= parameter |
403 Forbidden | Access Suspended | Account suspended or administrator endpoint accessed without credentials |
404 Not Found | Resource Missing | Target flight identifier or airport code does not exist |
429 Too Many Requests | Rate Limit Exceeded | Slow down request cadence; check Retry-After header |
500 Server Error | Internal Error | Telemetry node error; automated self-healing triggers automatically |