Traffic API

Traffic API

This API is used to receive the air traffic data collected by the network of INVOLI receivers or other sources, which are feeding the INVOLI.live server.

The traffic REST API is on the endpoint:

https://api.involi.live/traffic

Authorization is granted via a bearer token in the HTTP header.

Example: Authorization: bearer <token>

The token must be requested from the authentication server with your client id and client secret.


Sources

The API provides aircraft data from multiple sources. A list of available sources can be obtained by making a GET request on https://api.involi.live/traffic/sources. The response contains the ID of each source alongside a human-readable description. 

Example Response:

[ 
    {
        "id": "948e2a74-3293-4ae5-b95a-08738f3a6600",
        "description": "ADS-B data from INVOLI receivers"
    },
    {
        "id": "0bcaaf9a-f797-430a-980e-ead2e5656ba9",
        "description": "UAT data from INVOLI receivers"
    }
]
Field Type Unit Description 
id
 
string

ID of the data source

 
description (optional)
 
string

Description of the data source


Request

An HTTP GET request on the endpoint returns a full snapshot of current air traffic.

It is also possible to send a POST request with a JSON body containing options to narrow down the data.

Example request body:

{
    "boundingBox":
    {
        "southLatitude": 48.0,
        "northLatitude": 51.0,
        "westLongitude": 6.0,
        "eastLongitude": 7.0
    },
    "upperAltitude": 10000,
    "lowerAltitude": 0
}

Field Type Unit Description 
boundingBox.southLatitude (optional)

float

°

South latitude limit

boundingBox.northLatitude (optional)

float

°

North latitude limit

boundingBox.westLongitude (optional)

float

°

West longitude limit

boundingBox.eastLongitude (optional)

float

°

East longitude limit

upperAltitude (optional)
 
float
 
m

upper limit on aircraft altitude

 
lowerAltitude (optional)
 
float
 
m

lower limit on aircraft altitude

Altitude corresponds to elevation above WGS84 reference ellipsoid.

Warning: if request options are used, aircraft without known altitude will not be returned.


Data format

The API returns a list of aircraft records.

Example aircraft record:

"aircraft":{
   "ids":{
      "icao":"3006b5",
      "iid":"e1399607-ad09-46c3-9854-337bfa27d378"
   },
   "latitude":48.51804571636652,
   "longitude":13.047421242285054,
   "position_timestamp":[
      1711100527,
      277885249
   ],
   "wgs84_altitude":9372.6,
   "barometric_altitude":9144,
   "ground_speed":195.19201354382324,
   "vertical_speed":0,
   "ground_status":"airborne",
   "timestamp":[
      1711100527,
      652503876
   ],
   "course":299.8759926916894,
   "aircraft_type":"large_plane",
   "call_sign":"DLA97F",
   "source_id":"dc19dbbd-186a-4dad-9593-342461e20309"
}

Aircraft Fields Description:

Field Type Unit Description

source_id

string


ID of the source

ids.iid string   Internal aircraft ID
ids.icao string   ICAO 
ids.track string   Track ID
only for source: MLAT Mode A/C
ids.serial_number string   LEMAN tracker serial number
only for sources: Remote ID Broadcast, Remote ID Network
ids.uas_id string   UAS ID
only for sources: Remote ID Broadcast, Remote ID Network
ids.wifi_mac string   MAC address of the broadcasting device
only for source: Remote ID Broadcast
aircraft_type string enum Type of the aircraft, for example, small_plane.
latitude float °  
longitude float °  

position_timestamp

array

[s, ns]

Timestamp of the last position update (latitude and longitude)

wgs84_altitude float m Elevation above WGS84 reference ellipsoid
barometric_altitude float m Air pressure in terms of altitude in the Internal Standard Atmosphere
call_sign string   Call sign advertised by the aircraft
registration (*)
 string   Official registration of the aircraft.
squawk string   4-digit transponder squawk
course (**)
 float ° Aircraft tracking over ground. Degrees from North
heading (***)
 float ° Aircraft orientation (nose). Degrees from North
ground_speed float m/s The horizontal speed of the aircraft relative to the ground
ground_status string enum  Airborne, on-ground or unknown
timestamp array [s, ns] Original message timestamp indicating reception time, set in the receiver (separated in seconds and nanoseconds)
vertical_speed float m/s The vertical component of the aircraft's speed. The vertical speed is positive when gaining altitude (going up) and negative when losing altitude.

All fields are optional except ids and source_id. This is because not all information is available depending on the source.

(*) - Often the registration field is not present, because it is not transmitted by the airplane

(**), (***) - These two information elements are not always the same, even if they look similar. The heading is the direction in which the airplane nose is pointing and is often not included. Instead, the course is used.


Aircraft Types:

  • unknown
  • small_plane
  • large_plane
  • helicopter
  • paraglider
  • parachute
  • balloon
  • drone
  • ground_obstacle
  • ground_vehicle
  • ground_operator

Ground Status:

  • on_ground
  • airborne
  • unknown


​ ​ ​ ​ ​ ​ ​Previous​​​​Next