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