OpenSky Network State Vectors API
Endpoints for retrieving real-time and historical aircraft state vectors (position, velocity, altitude, etc.).
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/opensky:opensky-state-vectors-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: OpenSky Network REST 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:
Error:
type: object
properties:
message:
type: string
description: Human-readable error message.
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
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