The OpenSky Network API documentation

This is the official documentation of the OpenSky Network’s live API. The API lets you retrieve live airspace information for research and non-commerical purposes.

Please note that the API does not provide commmercial flight data such as airport schedules, delays or similar information that cannot be derived from ADS-B data contents!

Information is generally provided in the form of State Vectors (see below). The following paragraphs will help you understand how we represent an aircraft’s state and how to use it. There is also a little more specific documentation available for our REST API. We provide a Python language binding and a Java language binding for the REST API.

Citation and Terms of Use

If you create a publication (including web pages, papers published by a third party, and publicly available presentations) using data from the OpenSky Network data set, you should cite the original OpenSky paper as follows:

Matthias Schäfer, Martin Strohmeier, Vincent Lenders, Ivan Martinovic and Matthias Wilhelm.
"Bringing Up OpenSky: A Large-scale ADS-B Sensor Network for Research".
In Proceedings of the 13th IEEE/ACM International Symposium on Information Processing in Sensor Networks (IPSN), pages 83-94, April 2014.

You can additionally mention our URL, where appropriate:

The OpenSky Network, https://opensky-network.org

See our terms and conditions for more details on the data license model. If you want to retrieve live flight information for commercial purposes, please contact us.

State Vectors

Airplanes seen by the OpenSky Network are associated with flight state information derived from ADS-B and Mode S messages. The state of an aircraft is a summary of all tracking information (mainly position, velocity, and identity) at a certain point in time. These states of aircraft can be retrieved as state vectors in the form of a JSON object.

In ADS-B, each aircraft (actually each transponder) is identified with a unique address, the ICAO 24-bit address. Usually this address is displayed in its 6-character hex representation (e.g. c0ffee).

As soon as an ADS-B message of an airplane arrives at our servers, we create a record for the aircraft – the so called state vector. All information required to track the airplane, including its identity (ICAO address + call sign), time information (Unix timestamps), and spatial information (position, velocity, heading, …) will be represented in this state vector.

Example: Let’s assume an airplane with the address c0ffee enters the airspace covered by OpenSky on March 26, 2016 at about 11:13:44. At 11:13:44.097 it tells us its speed (230 m/s) and heading (30° clock-wise from north). We then create the following record:

“At time 1458987225, we’ve seen c0ffee flying at 230m/s into direction 30°. Velocity was updated at 1458987224.097.”

Within the next couple of microseconds, more information arrives and the state vector becomes filled. At time 11:13:44.15, the aircraft first tells us its call-sign CONAIR. At time 11:13:44.27, we learn its latitude (51.89°), longitude (1.28°), and altitude (11.5 km). Its state vector then looks like this:

“At time 1458987225, we’ve seen c0ffee (call-sign CONAIR) at latitude 51.89°, longitude 1.28°, and altitude 11500m flying at 230m/s into direction 30°. Velocity was updated at 1458987224.097. Position was updated at 1458987224.27.”

You might have noticed that the first timestamp in the state vector is rounded to the next full second. This is because we keep updating this state vector until 11:13:45 and then release it to the API. Consequently, the state vector returned by the API at 11:13:45 contains the most recent information known at that time.

Validity

So what happens if we do not receive any position or velocity update for a while? Well, if the last known position of the airplane is not older than 15 seconds, we will just reuse it. If we do not know any prior position or if the last known position is too old (>15s), we will omit the position information in the state vector. The same applies for velocity information.

If we do not receive any position or velocity update for a duration of 15 seconds, we consider the state vector obsolete and the API won’t return any further state vector for the respective airplane.

Further Reading