Endpoints for retrieving flight records including arrivals, departures, and flights by aircraft.
openapi: 3.1.0
info:
title: OpenSky Network REST Flights 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: Flights
description: Endpoints for retrieving flight records including arrivals, departures, and flights by aircraft.
paths:
/flights/all:
get:
operationId: getFlightsAll
summary: Get flights in time interval
description: Retrieve flights for a given time interval. The time interval must not exceed 2 hours. Returns all flights that were seen within the time interval.
tags:
- Flights
parameters:
- name: begin
in: query
required: true
schema:
type: integer
description: Start of time interval to retrieve flights for as Unix time (seconds since epoch).
- name: end
in: query
required: true
schema:
type: integer
description: End of time interval to retrieve flights for as Unix time (seconds since epoch). Must be within 2 hours of begin.
responses:
'200':
description: Successful response with an array of flights.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FlightObject'
'400':
description: Bad request. The time interval may exceed the 2-hour maximum.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No flights found for the given time interval.
content: {}
'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.
/flights/aircraft:
get:
operationId: getFlightsByAircraft
summary: Get flights by aircraft
description: Retrieve flights for a particular aircraft within a given time interval. The time interval must not exceed 2 days. Returns all flights for the specified aircraft in the given time range.
tags:
- Flights
parameters:
- name: icao24
in: query
required: true
schema:
type: string
description: Unique ICAO 24-bit address of the transponder in lower-case hex string representation (e.g. 3c6444).
- name: begin
in: query
required: true
schema:
type: integer
description: Start of time interval to retrieve flights for as Unix time (seconds since epoch).
- name: end
in: query
required: true
schema:
type: integer
description: End of time interval to retrieve flights for as Unix time (seconds since epoch). Must be within 2 days of begin.
responses:
'200':
description: Successful response with an array of flights for the specified aircraft.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FlightObject'
'400':
description: Bad request. The time interval may exceed the 2-day maximum.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No flights found for the given aircraft and time interval.
content: {}
'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.
/flights/arrival:
get:
operationId: getFlightsByArrivalAirport
summary: Get arrivals by airport
description: Retrieve flights arriving at a specific airport within a given time interval. The time interval must not exceed 2 days. Returns all flights that arrived at the specified airport in the given time range.
tags:
- Flights
parameters:
- name: airport
in: query
required: true
schema:
type: string
description: ICAO identifier for the airport (e.g. EDDF for Frankfurt Airport).
- name: begin
in: query
required: true
schema:
type: integer
description: Start of time interval to retrieve flights for as Unix time (seconds since epoch).
- name: end
in: query
required: true
schema:
type: integer
description: End of time interval to retrieve flights for as Unix time (seconds since epoch). Must be within 2 days of begin.
responses:
'200':
description: Successful response with an array of arrival flights.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FlightObject'
'400':
description: Bad request. The time interval may exceed the 2-day maximum.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No arrivals found for the given airport and time interval.
content: {}
'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.
/flights/departure:
get:
operationId: getFlightsByDepartureAirport
summary: Get departures by airport
description: Retrieve flights departing from a specific airport within a given time interval. The time interval should cover more than 2 days of UTC boundaries for best results. Returns all flights that departed from the specified airport in the given time range.
tags:
- Flights
parameters:
- name: airport
in: query
required: true
schema:
type: string
description: ICAO identifier for the airport (typically uppercase, e.g. EDDF for Frankfurt Airport).
- name: begin
in: query
required: true
schema:
type: integer
description: Start of time interval to retrieve flights for as Unix time (seconds since epoch).
- name: end
in: query
required: true
schema:
type: integer
description: End of time interval to retrieve flights for as Unix time (seconds since epoch).
responses:
'200':
description: Successful response with an array of departure flights.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FlightObject'
'400':
description: Bad request. Invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No departures found for the given airport and time interval.
content: {}
'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.
components:
schemas:
FlightObject:
type: object
description: A flight record representing a single flight detected by the OpenSky Network.
properties:
icao24:
type: string
description: Unique ICAO 24-bit address of the transponder in hex string representation. All letters are lower case.
example: 3c6444
firstSeen:
type: integer
description: Estimated time of departure for the flight as Unix time (seconds since epoch).
example: 1517220000
estDepartureAirport:
type: string
nullable: true
description: ICAO code of the estimated departure airport. Can be null if the airport could not be identified.
example: EDDF
lastSeen:
type: integer
description: Estimated time of arrival for the flight as Unix time (seconds since epoch).
example: 1517223600
estArrivalAirport:
type: string
nullable: true
description: ICAO code of the estimated arrival airport. Can be null if the airport could not be identified.
example: EGLL
callsign:
type: string
nullable: true
description: Callsign of the vehicle (8 chars). Can be null if no callsign has been received. If the vehicle transmits multiple callsigns during the flight, the one seen most frequently is used.
example: 'DLH400 '
estDepartureAirportHorizDistance:
type: integer
nullable: true
description: Horizontal distance of the last received airborne position to the estimated departure airport in meters.
example: 1250
estDepartureAirportVertDistance:
type: integer
nullable: true
description: Vertical distance of the last received airborne position to the estimated departure airport in meters.
example: 304
estArrivalAirportHorizDistance:
type: integer
nullable: true
description: Horizontal distance of the last received airborne position to the estimated arrival airport in meters.
example: 1800
estArrivalAirportVertDistance:
type: integer
nullable: true
description: Vertical distance of the last received airborne position to the estimated arrival airport in meters.
example: 152
departureAirportCandidatesCount:
type: integer
description: Number of other possible departure airports in short distance to estDepartureAirport.
example: 0
arrivalAirportCandidatesCount:
type: integer
description: Number of other possible arrival airports in short distance to estArrivalAirport.
example: 1
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