OpenSky REST API

The root URL of our REST API is:

https://opensky-network.org/api

There are several functions available to retrieve state vectors, flights and tracks for the whole network, a particular sensor, or a particular aircraft. Note that the functions to retrieve state vectors of sensors other than your own are rate limited (see Limitations).

All State Vectors

The following API call can be used to retrieve any state vector of the OpenSky. Please note that rate limits apply for this call (see Limitations). For API calls without rate limitation, see Own State Vectors.

Operation

GET /states/all

Request

You can (optionally) request state vectors for particular airplanes or times using the following request parameters:

Property Type Description
time integer The time in seconds since epoch (Unix time stamp to retrieve states for. Current time will be used if omitted.
icao24 string One or more ICAO24 transponder addresses represented by a hex string (e.g. abc9f3). To filter multiple ICAO24 append the property once for each address. If omitted, the state vectors of all aircraft are returned.

In addition to that, it is possible to query a certain area defined by a bounding box of WGS84 coordinates. For this purpose, add all of the following parameters:

Property Type Description
lamin float lower bound for the latitude in decimal degrees
lomin float lower bound for the longitude in decimal degrees
lamax float upper bound for the latitude in decimal degrees
lomax float upper bound for the longitude in decimal degrees

Example query with time and aircraft: https://opensky-network.org/api/states/all?time=1458564121&icao24=3c6444

Example query with bounding box covering Switzerland: https://opensky-network.org/api/states/all?lamin=45.8389&lomin=5.9962&lamax=47.8229&lomax=10.5226

Response

The response is a JSON object with the following properties

Property Type Description
time integer The time which the state vectors in this response are associated with. All vectors represent the state of a vehicle with the interval \([time - 1, time]\).
states array The state vectors.

The states property is a two-dimensional array. Each row represents a state vector and contains the following fields:

Index Property Type Description
0 icao24 string Unique ICAO 24-bit address of the transponder in hex string representation.
1 callsign string Callsign of the vehicle (8 chars). Can be null if no callsign has been received.
2 origin_country string Country name inferred from the ICAO 24-bit address.
3 time_position int Unix timestamp (seconds) for the last position update. Can be null if no position report was received by OpenSky within the past 15s.
4 last_contact int Unix timestamp (seconds) for the last update in general. This field is updated for any new, valid message received from the transponder.
5 longitude float WGS-84 longitude in decimal degrees. Can be null.
6 latitude float WGS-84 latitude in decimal degrees. Can be null.
7 baro_altitude float Barometric altitude in meters. Can be null.
8 on_ground boolean Boolean value which indicates if the position was retrieved from a surface position report.
9 velocity float Velocity over ground in m/s. Can be null.
10 true_track float True track in decimal degrees clockwise from north (north=0°). Can be null.
11 vertical_rate float Vertical rate in m/s. A positive value indicates that the airplane is climbing, a negative value indicates that it descends. Can be null.
12 sensors int[] IDs of the receivers which contributed to this state vector. Is null if no filtering for sensor was used in the request.
13 geo_altitude float Geometric altitude in meters. Can be null.
14 squawk string The transponder code aka Squawk. Can be null.
15 spi boolean Whether flight status indicates special purpose indicator.
16 position_source int Origin of this state’s position: 0 = ADS-B, 1 = ASTERIX, 2 = MLAT

Limitations

Limitiations for anonymous (unauthenticated) users

Anonymous are those users who access the API without using credentials. The limitations for anonymous users are:

  • Anonymous users can only get the most recent state vectors, i.e. the time parameter will be ignored.
  • Anonymous users can only retrieve data with a time resultion of 10 seconds. That means, the API will return state vectors for time \(now - (now\ mod\ 10)\).

Limitations for OpenSky users

An OpenSky user is anybody who uses a valid OpenSky account (see below) to access the API. The rate limitations for OpenSky users are:

  • OpenSky users can retrieve data of up to 1 hour in the past. If the time parameter has a value \(t<now-3600\) the API will return 400 Bad Request.
  • OpenSky users can retrieve data with a time resultion of 5 seconds. That means, if the time parameter was set to \(t\), the API will return state vectors for time \(t - (t\ mod\ 5)\).

Note

You can retrieve all state vectors received by your receivers without any restrictions. See Own State Vectors.

Examples

Retrieve all states as an anonymous user:

$ curl -s "https://opensky-network.org/api/states/all" | python -m json.tool

Retrieve all states as an authenticated OpenSky user:

$ curl -s "https://USERNAME:PASSWORD@opensky-network.org/api/states/all" | python -m json.tool

Retrieve states of two particular airplanes:

$ curl -s "https://opensky-network.org/api/states/all?icao24=3c6444&icao24=3e1bf9" | python -m json.tool

Own State Vectors

The following API call can be used to retrieve state vectors for your own sensors without rate limitations. Note that authentication is required for this operation, otherwise you will get a 403 - Forbidden.

Operation

GET /states/own

Request

Pass one of the following (optional) properties as request parameters to the GET request.

Property Type Description
time integer The time in seconds since epoch (Unix timestamp to retrieve states for. Current time will be used if omitted.
icao24 string One or more ICAO24 transponder addresses represented by a hex string (e.g. abc9f3). To filter multiple ICAO24 append the property once for each address. If omitted, the state vectors of all aircraft are returned.
serials integer Retrieve only states of a subset of your receivers. You can pass this argument several time to filter state of more than one of your receivers. In this case, the API returns all states of aircraft that are visible to at least one of the given receivers.

Response

The response is a JSON object with the following properties

Property Type Description
time integer The time which the state vectors in this response are associated with. All vectors represent the state of a vehicle with the interval \([time - 1, time]\).
states array The state vectors.

The states property is a two-dimensional array. Each row represents a state vector and contains the following fields:

Index Property Type Description
0 icao24 string Unique ICAO 24-bit address of the transponder in hex string representation.
1 callsign string Callsign of the vehicle (8 chars). Can be null if no callsign has been received.
2 origin_country string Country name inferred from the ICAO 24-bit address.
3 time_position int Unix timestamp (seconds) for the last position update. Can be null if no position report was received by OpenSky within the past 15s.
4 last_contact int Unix timestamp (seconds) for the last update in general. This field is updated for any new, valid message received from the transponder.
5 longitude float WGS-84 longitude in decimal degrees. Can be null.
6 latitude float WGS-84 latitude in decimal degrees. Can be null.
7 baro_altitude float Barometric altitude in meters. Can be null.
8 on_ground boolean Boolean value which indicates if the position was retrieved from a surface position report.
9 velocity float Velocity over ground in m/s. Can be null.
10 true_track float True track in decimal degrees clockwise from north (north=0°). Can be null.
11 vertical_rate float Vertical rate in m/s. A positive value indicates that the airplane is climbing, a negative value indicates that it descends. Can be null.
12 sensors int[] IDs of the receivers which contributed to this state vector. Is null if no filtering for sensor was used in the request.
13 geo_altitude float Geometric altitude in meters. Can be null.
14 squawk string The transponder code aka Squawk. Can be null.
15 spi boolean Whether flight status indicates special purpose indicator.
16 position_source int Origin of this state’s position: 0 = ADS-B, 1 = ASTERIX, 2 = MLAT

Examples

Retrieve states for all sensors that belong to you:

$ curl -s "https://USERNAME:PASSWORD@opensky-network.org/api/states/own" | python -m json.tool

Retrieve states as seen by a specific sensor with serial 123456

$ curl -s "https://USERNAME:PASSWORD@opensky-network.org/api/states/own?serials=123456" | python -m json.tool

Retrieve states for several receivers:

$ curl -s "https://USERNAME:PASSWORD@opensky-network.org/api/states/own?serials=123456&serials=98765" | python -m json.tool

Flights in Time Interval

This API call retrieves flights for a certain time interval [begin, end]. If no flights are found for the given time period, HTTP status 404 - Not found is returned with an empty response body.

Operation

GET /flights/all

Request

These are the required request parameters:

Property Type Description
begin integer Start of time interval to retrieve flights for as Unix time (seconds since epoch)
end integer End of time interval to retrieve flights for as Unix time (seconds since epoch)

The given time interval must not be larger than two hours!

Response

The response is a JSON array of flights where each flight is an object with the following properties:

Property Type Description
icao24 string Unique ICAO 24-bit address of the transponder in hex string representation. All letters are lower case.
firstSeen integer Estimated time of departure for the flight as Unix time (seconds since epoch).
estDepartureAirport string ICAO code of the estimated departure airport. Can be null if the airport could not be identified.
lastSeen integer Estimated time of arrival for the flight as Unix time (seconds since epoch)
estArrivalAirport string ICAO code of the estimated arrival airport. Can be null if the airport could not be identified.
callsign string Callsign of the vehicle (8 chars). Can be null if no callsign has been received. If the vehicle transmits multiple callsigns during the flight, we take the one seen most frequently
estDepartureAirportHorizDistance integer Horizontal distance of the last received airborne position to the estimated departure airport in meters
estDepartureAirportVertDistance integer Vertical distance of the last received airborne position to the estimated departure airport in meters
estArrivalAirportHorizDistance integer Horizontal distance of the last received airborne position to the estimated arrival airport in meters
estArrivalAirportVertDistance integer Vertical distance of the last received airborne position to the estimated arrival airport in meters
departureAirportCandidatesCount integer Number of other possible departure airports. These are airports in short distance to estDepartureAirport.
arrivalAirportCandidatesCount integer Number of other possible departure airports. These are airports in short distance to estArrivalAirport.

Examples

Get flights from 12pm to 1pm on Jan 29 2018:

$ curl -s "https://USERNAME:PASSWORD@opensky-network.org/api/flights/all?begin=1517227200&end=1517230800" | python -m json.tool

Flights by Aircraft

This API call retrieves flights for a particular aircraft within a certain time interval. Resulting flights departed and arrived within [begin, end]. If no flights are found for the given period, HTTP stats 404 - Not found is returned with an empty response body.

Operation

GET /flights/aircraft

Request

These are the required request parameters:

Property Type Description
icao24 string Unique ICAO 24-bit address of the transponder in hex string representation. All letters need to be lower case
begin integer Start of time interval to retrieve flights for as Unix time (seconds since epoch)
end integer End of time interval to retrieve flights for as Unix time (seconds since epoch)

The given time interval must not be larger than 30 days!

Response

The response is a JSON array of flights where each flight is an object with the following properties:

Property Type Description
icao24 string Unique ICAO 24-bit address of the transponder in hex string representation. All letters are lower case.
firstSeen integer Estimated time of departure for the flight as Unix time (seconds since epoch).
estDepartureAirport string ICAO code of the estimated departure airport. Can be null if the airport could not be identified.
lastSeen integer Estimated time of arrival for the flight as Unix time (seconds since epoch)
estArrivalAirport string ICAO code of the estimated arrival airport. Can be null if the airport could not be identified.
callsign string Callsign of the vehicle (8 chars). Can be null if no callsign has been received. If the vehicle transmits multiple callsigns during the flight, we take the one seen most frequently
estDepartureAirportHorizDistance integer Horizontal distance of the last received airborne position to the estimated departure airport in meters
estDepartureAirportVertDistance integer Vertical distance of the last received airborne position to the estimated departure airport in meters
estArrivalAirportHorizDistance integer Horizontal distance of the last received airborne position to the estimated arrival airport in meters
estArrivalAirportVertDistance integer Vertical distance of the last received airborne position to the estimated arrival airport in meters
departureAirportCandidatesCount integer Number of other possible departure airports. These are airports in short distance to estDepartureAirport.
arrivalAirportCandidatesCount integer Number of other possible departure airports. These are airports in short distance to estArrivalAirport.

Examples

Get flights for D-AIZZ (3c675a) on Jan 29 2018:

$ curl -s "https://USERNAME:PASSWORD@opensky-network.org/api/flights/aircraft?icao24=3c675a&begin=1517184000&end=1517270400" | python -m json.tool

Arrivals by Airport

Retrieve flights for a certain airport which arrived within a given time interval [begin, end]. If no flights are found for the given period, HTTP stats 404 - Not found is returned with an empty response body.

Operation

GET /flights/arrival

Request

These are the required request parameters:

Property Type Description
airport string ICAO identier for the airport
begin integer Start of time interval to retrieve flights for as Unix time (seconds since epoch)
end integer End of time interval to retrieve flights for as Unix time (seconds since epoch)

The given time interval must not be larger than seven days!

Response

The response is a JSON array of flights where each flight is an object with the following properties:

Property Type Description
icao24 string Unique ICAO 24-bit address of the transponder in hex string representation. All letters are lower case.
firstSeen integer Estimated time of departure for the flight as Unix time (seconds since epoch).
estDepartureAirport string ICAO code of the estimated departure airport. Can be null if the airport could not be identified.
lastSeen integer Estimated time of arrival for the flight as Unix time (seconds since epoch)
estArrivalAirport string ICAO code of the estimated arrival airport. Can be null if the airport could not be identified.
callsign string Callsign of the vehicle (8 chars). Can be null if no callsign has been received. If the vehicle transmits multiple callsigns during the flight, we take the one seen most frequently
estDepartureAirportHorizDistance integer Horizontal distance of the last received airborne position to the estimated departure airport in meters
estDepartureAirportVertDistance integer Vertical distance of the last received airborne position to the estimated departure airport in meters
estArrivalAirportHorizDistance integer Horizontal distance of the last received airborne position to the estimated arrival airport in meters
estArrivalAirportVertDistance integer Vertical distance of the last received airborne position to the estimated arrival airport in meters
departureAirportCandidatesCount integer Number of other possible departure airports. These are airports in short distance to estDepartureAirport.
arrivalAirportCandidatesCount integer Number of other possible departure airports. These are airports in short distance to estArrivalAirport.

Examples

Get all flights arriving at Frankfurt International Airport (EDDF) from 12pm to 1pm on Jan 29 2018:

$ curl -s "https://USERNAME:PASSWORD@opensky-network.org/api/flights/arrival?airport=EDDF&begin=1517227200&end=1517230800" | python -m json.tool

Departures by Airport

Retrieve flights for a certain airport which departed within a given time interval [begin, end]. If no flights are found for the given period, HTTP stats 404 - Not found is returned with an empty response body.

Operation

GET /flights/departure

Request

These are the required request parameters:

Property Type Description
airport string ICAO identier for the airport (usually upper case)
begin integer Start of time interval to retrieve flights for as Unix time (seconds since epoch)
end integer End of time interval to retrieve flights for as Unix time (seconds since epoch)

The given time interval must not be larger than seven days!

Response

The response is a JSON array of flights where each flight is an object with the following properties

Property Type Description
icao24 string Unique ICAO 24-bit address of the transponder in hex string representation. All letters are lower case.
firstSeen integer Estimated time of departure for the flight as Unix time (seconds since epoch).
estDepartureAirport string ICAO code of the estimated departure airport. Can be null if the airport could not be identified.
lastSeen integer Estimated time of arrival for the flight as Unix time (seconds since epoch)
estArrivalAirport string ICAO code of the estimated arrival airport. Can be null if the airport could not be identified.
callsign string Callsign of the vehicle (8 chars). Can be null if no callsign has been received. If the vehicle transmits multiple callsigns during the flight, we take the one seen most frequently
estDepartureAirportHorizDistance integer Horizontal distance of the last received airborne position to the estimated departure airport in meters
estDepartureAirportVertDistance integer Vertical distance of the last received airborne position to the estimated departure airport in meters
estArrivalAirportHorizDistance integer Horizontal distance of the last received airborne position to the estimated arrival airport in meters
estArrivalAirportVertDistance integer Vertical distance of the last received airborne position to the estimated arrival airport in meters
departureAirportCandidatesCount integer Number of other possible departure airports. These are airports in short distance to estDepartureAirport.
arrivalAirportCandidatesCount integer Number of other possible departure airports. These are airports in short distance to estArrivalAirport.

Examples

Get all flights departing at Frankfurt International Airport (EDDF) from 12pm to 1pm on Jan 29 2018:

$ curl -s "https://USERNAME:PASSWORD@opensky-network.org/api/flights/departure?airport=EDDF&begin=1517227200&end=1517230800" | python -m json.tool

Track by Aircraft

Retrieve the trajectory for a certain aircraft at a given time. The trajectory is a list of waypoints containing position, barometric altitude, true track and an on-ground flag.

In contrast to state vectors, trajectories do not contain all information we have about the flight, but rather show the aircraft’s general movement pattern. For this reason, waypoints are selected among available state vectors given the following set of rules:

  • The first point is set immediately after the the aircraft’s expected departure, or after the network received the first poisition when the aircraft entered its reception range.
  • The last point is set right before the aircraft’s expected arrival, or the aircraft left the networks reception range.
  • There is a waypoint at least every 15 minutes when the aircraft is in-flight.
  • A waypoint is added if the aircraft changes its track more than 2.5°.
  • A waypoint is added if the aircraft changes altitude by more than 100m (~330ft).
  • A waypoint is added if the on-ground state changes.

Tracks are strongly related to flights. Internally, we compute flights and tracks within the same processing step. As such, it may be benificial to retrieve a list of flights with the API methods from above, and use these results with the given time stamps to retrieve detailed track information.

Operation

GET /tracks

Request

Property Type Description
icao24 string Unique ICAO 24-bit address of the transponder in hex string representation. All letters need to be lower case
time integer Unix time in seconds since epoch. It can be any time betwee start and end of a known flight. If time = 0, get the live track if there is any flight ongoing for the given aircraft.

Response

The response is a JSON object with the following properties:

Property Type Description
icao24 string Unique ICAO 24-bit address of the transponder in lower case hex string representation.
startTime integer Time of the first waypoint in seconds since epoch (Unix time).
endTime integer Time of the last waypoint in seconds since epoch (Unix time).
calllsign string Callsign (8 characters) that holds for the whole track. Can be null.
path array Waypoints of the trajectory (description below).

Waypoints are represented as JSON arrays to save bandwidth. Each point contains the following information:

Index Property Type Description
0 time integer Time which the given waypoint is associated with in seconds since epoch (Unix time).
1 latitude float WGS-84 latitude in decimal degrees. Can be null.
2 longitude float WGS-84 longitude in decimal degrees. Can be null.
3 baro_altitude float Barometric altitude in meters. Can be null.
4 true_track float True track in decimal degrees clockwise from north (north=0°). Can be null.
5 on_ground boolean Boolean value which indicates if the position was retrieved from a surface position report.

Limitations

It is not possible to access flight tracks from more than 30 days in the past.

Examples

Get the live track for aircraft with transponder address 3c4b26 (D-ABYF)

$ curl -s "https://USERNAME:PASSWORD@opensky-network.org/api/tracks/all?icao24=3c4b26&time=0"