Endpoints for retrieving real-time and historical aircraft state vectors (position, velocity, altitude, etc.).
openapi: 3.1.0
info:
title: OpenSky Network REST Flights State Vectors API
description: REST API for retrieving real-time and historical ADS-B aircraft state vectors, flight tracks, and airport arrival and departure data from the OpenSky Network crowd-sourced receiver network. Intended for non-commercial research and educational use.
version: 1.0.0
termsOfService: https://opensky-network.org/about/terms-of-use
contact:
name: OpenSky Network
email: contact@opensky-network.org
url: https://opensky-network.org/about/contact
license:
name: OpenSky Network Terms of Use
url: https://opensky-network.org/about/terms-of-use
servers:
- url: https://opensky-network.org/api
description: OpenSky Network REST API
security:
- {}
- bearerAuth: []
tags:
- name: State Vectors
description: Endpoints for retrieving real-time and historical aircraft state vectors (position, velocity, altitude, etc.).
paths:
/states/all:
get:
operationId: getStateVectorsAll
summary: Get all state vectors
description: Retrieve any state vector of the OpenSky Network. Returns state vectors for all aircraft currently tracked. Rate limits apply (see rate limiting documentation). Anonymous users receive 10-second resolution; authenticated users receive 5-second resolution.
tags:
- State Vectors
parameters:
- name: time
in: query
required: false
schema:
type: integer
description: The time in seconds since epoch (Unix timestamp) to retrieve state vectors for. Current time is used if omitted.
- name: icao24
in: query
required: false
schema:
type: array
items:
type: string
style: form
explode: true
description: One or more ICAO24 transponder addresses represented by a hex string (e.g. abc9f3). To filter multiple aircraft, repeat this parameter.
- name: lamin
in: query
required: false
schema:
type: number
format: float
minimum: -90
maximum: 90
description: Lower bound for the latitude in decimal degrees of the bounding box.
- name: lomin
in: query
required: false
schema:
type: number
format: float
minimum: -180
maximum: 180
description: Lower bound for the longitude in decimal degrees of the bounding box.
- name: lamax
in: query
required: false
schema:
type: number
format: float
minimum: -90
maximum: 90
description: Upper bound for the latitude in decimal degrees of the bounding box.
- name: lomax
in: query
required: false
schema:
type: number
format: float
minimum: -180
maximum: 180
description: Upper bound for the longitude in decimal degrees of the bounding box.
- name: extended
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
description: Set to 1 to request the extended state vector format which includes aircraft category (index 17).
responses:
'200':
description: Successful response with state vectors.
content:
application/json:
schema:
$ref: '#/components/schemas/StateVectorResponse'
examples:
switzerlandBoundingBox:
summary: State vectors over Switzerland
value:
time: 1458564121
states:
- - 3c6444
- 'DLH400 '
- Germany
- 1458564120
- 1458564121
- 8.5432
- 47.2231
- 9144.0
- false
- 251.2
- 87.5
- 0.0
- null
- 9448.8
- '1000'
- false
- 0
'400':
description: Bad request. Historical queries may exceed the allowed time range.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized. The Bearer token has expired. Request a new token and retry.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too many requests. Credit limit exhausted.
headers:
X-Rate-Limit-Retry-After-Seconds:
schema:
type: integer
description: Number of seconds to wait before retrying.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/states/own:
get:
operationId: getOwnStateVectors
summary: Get own state vectors
description: Retrieve state vectors for your own sensors. This endpoint requires authentication and is not rate limited for your own receivers. Returns state vectors from sensors you operate.
tags:
- State Vectors
security:
- bearerAuth: []
parameters:
- name: time
in: query
required: false
schema:
type: integer
description: The time in seconds since epoch (Unix timestamp) to retrieve state vectors for. Current time is used if omitted.
- name: icao24
in: query
required: false
schema:
type: array
items:
type: string
style: form
explode: true
description: One or more ICAO24 transponder addresses represented by a hex string. To filter multiple aircraft, repeat this parameter.
- name: serials
in: query
required: false
schema:
type: array
items:
type: integer
style: form
explode: true
description: Receiver serial numbers to filter results. To filter for multiple receivers, repeat this parameter.
responses:
'200':
description: Successful response with own state vectors.
content:
application/json:
schema:
$ref: '#/components/schemas/StateVectorResponse'
'401':
description: Unauthorized. Authentication is required for this endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden. Unauthenticated access to /states/own is not permitted.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
StateVectorResponse:
type: object
description: Response containing a collection of state vectors representing the current state of aircraft.
properties:
time:
type: integer
description: 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].
example: 1458564121
states:
type: array
nullable: true
description: The state vectors as a two-dimensional array. Each row represents a state vector with 18 indexed fields.
items:
type: array
description: A single state vector with 18 fields indexed 0-17.
items: {}
prefixItems:
- type: string
description: 'icao24: Unique ICAO 24-bit address of the transponder in hex string representation. All letters are lower case.'
- type: string
nullable: true
description: 'callsign: Callsign of the vehicle (8 chars). Can be null if no callsign has been received.'
- type: string
description: 'origin_country: Country name inferred from the ICAO 24-bit address.'
- type: integer
nullable: true
description: 'time_position: Unix timestamp (seconds) for the last position update. Can be null if no position report was received within the past 15s.'
- type: integer
description: 'last_contact: Unix timestamp (seconds) for the last update in general.'
- type: number
format: float
nullable: true
description: 'longitude: WGS-84 longitude in decimal degrees. Can be null.'
- type: number
format: float
nullable: true
description: 'latitude: WGS-84 latitude in decimal degrees. Can be null.'
- type: number
format: float
nullable: true
description: 'baro_altitude: Barometric altitude in meters. Can be null.'
- type: boolean
description: 'on_ground: Boolean value which indicates if the position was retrieved from a surface position report.'
- type: number
format: float
nullable: true
description: 'velocity: Velocity over ground in m/s. Can be null.'
- type: number
format: float
nullable: true
description: 'true_track: True track in decimal degrees clockwise from north (north=0 degrees). Can be null.'
- type: number
format: float
nullable: true
description: 'vertical_rate: Vertical rate in m/s. Positive indicates climbing, negative indicates descending. Can be null.'
- type: array
items:
type: integer
nullable: true
description: 'sensors: IDs of the receivers which contributed to this state vector. Is null if no filtering for sensor was used in the request.'
- type: number
format: float
nullable: true
description: 'geo_altitude: Geometric altitude in meters. Can be null.'
- type: string
nullable: true
description: 'squawk: The transponder code aka Squawk. Can be null.'
- type: boolean
description: 'spi: Whether flight status indicates special purpose indicator.'
- type: integer
description: 'position_source: Origin of this state''s position. 0=ADS-B, 1=ASTERIX, 2=MLAT, 3=FLARM.'
enum:
- 0
- 1
- 2
- 3
- type: integer
description: 'category: Aircraft category. 0=No information, 1=No ADS-B Emitter Category Info, 2=Light (<15500 lbs), 3=Small (15500-75000 lbs), 4=Large (75000-300000 lbs), 5=High Vortex Large, 6=Heavy (>300000 lbs), 7=High Performance, 8=Rotorcraft, 9=Glider/sailplane, 10=Lighter-than-air, 11=Parachutist/Skydiver, 12=Ultralight/hang-glider, 13=Reserved, 14=UAV, 15=Space vehicle, 16=Surface Emergency, 17=Surface Service, 18=Point Obstacle, 19=Cluster Obstacle, 20=Line Obstacle.'
minimum: 0
maximum: 20
Error:
type: object
properties:
message:
type: string
description: Human-readable error message.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: OAuth2 client credentials Bearer token obtained from https://auth.opensky-network.org/auth/realms/opensky-network/protocol/openid-connect/token. Tokens expire after 30 minutes.
externalDocs:
description: OpenSky Network REST API Documentation
url: https://openskynetwork.github.io/opensky-api/rest.html