The REST API

class pyopensky.rest.REST

Bases: object

Wrapper to OpenSky REST API.

Credentials are fetched from the configuration file. REST API is documented here: https://opensky-network.org/apidoc/rest.html

All methods return standard structures. When calls are made from the traffic library, they return advanced structures.

aircraft(icao24, begin=None, end=None)

Returns a flight table associated to an aircraft.

Return type:

DataFrame

Official documentation

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.

arrival(airport, begin=None, end=None)

Returns a flight table associated to an airport.

By default, returns the current table. Otherwise, you may enter a specific date (as a string, as an epoch or as a datetime)

Return type:

DataFrame

Official documentation

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.

departure(airport, begin=None, end=None)

Returns a flight table associated to an airport.

By default, returns the current table. Otherwise, you may enter a specific date (as a string, as an epoch or as a datetime)

Return type:

DataFrame

Official documentation

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.

range(serial, day=None)

Wraps a polygon representing a sensor’s range.

By default, returns the current range. Otherwise, you may enter a specific day (as a string, as an epoch or as a datetime)

Return type:

Any

routes(callsign)

Returns the route associated to a callsign.

Return type:

tuple[str, str]

sensors(day=None)

The set of sensors serials you own (require authentication).

Return type:

set[str]

states(own=False, bounds=None, retry=5)

Returns the current state vectors from OpenSky REST API.

If own parameter is set to True, returns only the state vectors associated to own sensors (requires authentication)

bounds parameter can be a shape or a tuple of float.

Return type:

DataFrame

Official documentation

Limitations 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 resolution 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 resolution 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).

tracks(icao24, time=None)

Returns a Flight corresponding to a given aircraft.

Return type:

DataFrame

Official documentation

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 position 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 beneficial 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.