{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenSky Network REST 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"
    }
  ],
  "externalDocs": {
    "description": "OpenSky Network REST API Documentation",
    "url": "https://openskynetwork.github.io/opensky-api/rest.html"
  },
  "security": [
    {},
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "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."
      }
    },
    "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
                }
              ]
            }
          }
        }
      },
      "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
          }
        }
      },
      "TrackResponse": {
        "type": "object",
        "description": "A track representing the path of an aircraft over time.",
        "properties": {
          "icao24": {
            "type": "string",
            "description": "Unique ICAO 24-bit address of the transponder in hex string representation.",
            "example": "3c6444"
          },
          "startTime": {
            "type": "integer",
            "description": "Time of the first waypoint in Unix time (seconds since epoch).",
            "example": 1517220000
          },
          "endTime": {
            "type": "integer",
            "description": "Time of the last waypoint in Unix time (seconds since epoch).",
            "example": 1517223600
          },
          "callsign": {
            "type": "string",
            "nullable": true,
            "description": "Callsign of the aircraft. Can be null.",
            "example": "DLH400 "
          },
          "path": {
            "type": "array",
            "description": "Array of waypoints. Each waypoint is an array with 6 fields: [time, latitude, longitude, baro_altitude, true_track, on_ground].",
            "items": {
              "type": "array",
              "description": "A waypoint with 6 indexed fields.",
              "items": {},
              "prefixItems": [
                {
                  "type": "integer",
                  "description": "Unix timestamp of the waypoint."
                },
                {
                  "type": "number",
                  "format": "float",
                  "nullable": true,
                  "description": "WGS-84 latitude in decimal degrees."
                },
                {
                  "type": "number",
                  "format": "float",
                  "nullable": true,
                  "description": "WGS-84 longitude in decimal degrees."
                },
                {
                  "type": "number",
                  "format": "float",
                  "nullable": true,
                  "description": "Barometric altitude in meters."
                },
                {
                  "type": "number",
                  "format": "float",
                  "nullable": true,
                  "description": "True track in decimal degrees clockwise from north."
                },
                {
                  "type": "boolean",
                  "description": "Boolean indicating if the aircraft is on the ground."
                }
              ]
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable error message."
          }
        }
      }
    }
  },
  "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"
                }
              }
            }
          }
        }
      }
    },
    "/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."
              }
            }
          }
        }
      }
    },
    "/tracks": {
      "get": {
        "operationId": "getTrackByAircraft",
        "summary": "Get track by aircraft",
        "description": "Retrieve the trajectory for a certain aircraft at a given time. The track is a list of waypoints containing position, altitude, and velocity information. Set time to 0 to get the live track.",
        "tags": ["Tracks"],
        "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": "time",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Unix timestamp within the time window of the flight to retrieve. Set to 0 for the live track of the aircraft."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with the aircraft track.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Invalid parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No track found for the given aircraft and time.",
            "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."
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "State Vectors",
      "description": "Endpoints for retrieving real-time and historical aircraft state vectors (position, velocity, altitude, etc.)."
    },
    {
      "name": "Flights",
      "description": "Endpoints for retrieving flight records including arrivals, departures, and flights by aircraft."
    },
    {
      "name": "Tracks",
      "description": "Endpoints for retrieving aircraft trajectory tracks with detailed waypoint data."
    }
  ]
}