OpenSky Python API

Our official Python implementation can be found on github in this repository. See the README for installation instructions.

Retrieving Data

The API is encapsulated in a single class with two methods for retrieving state vectors.

class opensky_api.OpenSkyApi(username=None, password=None)

Main class of the OpenSky Network API. Instances retrieve data from OpenSky via HTTP

__init__(username=None, password=None)

Create an instance of the API client. If you do not provide username and password requests will be anonymous which imposes some limitations.

Parameters:
  • username – an OpenSky username (optional)
  • password – an OpenSky password for the given username (optional)
get_my_states(time_secs=0, icao24=None, serials=None)

Retrieve state vectors for your own sensors. Authentication is required for this operation. If time = 0 the most recent ones are taken. Optional filters may be applied for ICAO24 addresses and sensor serial numbers.

Parameters:
  • time_secs – time as Unix time stamp (seconds since epoch) or datetime. The datetime must be in UTC!
  • icao24 – optionally retrieve only state vectors for the given ICAO24 address(es). The parameter can either be a single address as str or an array of str containing multiple addresses
  • serials – optionally retrieve only states of vehicles as seen by the given sensor(s). The parameter can either be a single sensor serial number (int) or a list of serial numbers.
Returns:

OpenSkyStates if request was successful, None otherwise

get_states(time_secs=0, icao24=None, serials=None, bbox=())

Retrieve state vectors for a given time. If time = 0 the most recent ones are taken. Optional filters may be applied for ICAO24 addresses.

Parameters:
  • time_secs – time as Unix time stamp (seconds since epoch) or datetime. The datetime must be in UTC!
  • icao24 – optionally retrieve only state vectors for the given ICAO24 address(es). The parameter can either be a single address as str or an array of str containing multiple addresses
  • bbox – optionally retrieve state vectors within a bounding box. The bbox must be a tuple of exactly four values [min_latitude, max_latitude, min_longitude, max_latitude] each in WGS84 decimal degrees.
Returns:

OpenSkyStates if request was successful, None otherwise

Return Types

class opensky_api.OpenSkyStates(j)

Represents the state of the airspace as seen by OpenSky at a particular time. It has the following fields:

time - in seconds since epoch (Unix time stamp). Gives the validity period of all states. All vectors represent the state of a vehicle with the interval \([time - 1, time]\).
states - a list of StateVector or is None if there have been no states received
class opensky_api.StateVector(arr)

Represents the state of a vehicle at a particular time. It has the following fields:

icao24 - ICAO24 address of the transmitter in hex string representation.
callsign - callsign of the vehicle. Can be None if no callsign has been received.
origin_country - inferred through the ICAO24 address
time_position - seconds since epoch of last position report. Can be None if there was no position report received by OpenSky within 15s before.
last_contact - seconds since epoch of last received message from this transponder
longitude - in ellipsoidal coordinates (WGS-84) and degrees. Can be None
latitude - in ellipsoidal coordinates (WGS-84) and degrees. Can be None
geo_altitude - geometric altitude in meters. Can be None
on_ground - true if aircraft is on ground (sends ADS-B surface position reports).
velocity - over ground in m/s. Can be None if information not present
heading - in decimal degrees (0 is north). Can be None if information not present.
vertical_rate - in m/s, incline is positive, decline negative. Can be None if information not present.
sensors - serial numbers of sensors which received messages from the vehicle within the validity period of this state vector. Can be None if no filtering for sensor has been requested.
baro_altitude - barometric altitude in meters. Can be None
squawk - transponder code aka Squawk. Can be None
spi - special purpose indicator
position_source - origin of this state’s position: 0 = ADS-B, 1 = ASTERIX, 2 = MLAT, 3 = FLARM

Examples

Without any authentication you should only retrieve state vectors every 10 seconds. Any higher rate is unnecessary due to the rate limitations. Example for retrieving all states without authentication:

from opensky_api import OpenSkyApi

api = OpenSkyApi()
states = api.get_states()
for s in states.states:
    print("(%r, %r, %r, %r)" % (s.longitude, s.latitude, s.baro_altitude, s.velocity))

Example for retrieving all state vectors currently received by your receivers (no rate limit):

from opensky_api import OpenSkyApi

api = OpenSkyApi(USERNAME, PASSWORD)
states = api.get_my_states()
print(states)
for s in states.states:
    print(s.sensors)

It is also possible to retrieve state vectors for a certain area. For this purpose, you need to provide a bounding box. It is defined by lower and upper bounds for longitude and latitude. The following example shows how to retrieve data for a bounding box which encompasses Switzerland:

from opensky_api import OpenSkyApi

api = OpenSkyApi()
# bbox = (min latitude, max latitude, min longitude, max longitude)
states = api.get_states(bbox=(45.8389, 47.8229, 5.9962, 10.5226))
for s in states.states:
    print("(%r, %r, %r, %r)" % (s.longitude, s.latitude, s.baro_altitude, s.velocity))