ADS-B Exchange Geopolitical Filtering API

openapi: 3.2.0
info:
  title: ADSB Exchange Geopolitical Filtering API
  description: 'The ADSB Exchange API provides real-time access to live global flight data,

    enabling retrieval of detailed information on aircraft positions, flight events, historical trace files,

    and many more aviation metrics.'
  termsOfService: https://www.adsbexchange.com/terms-of-use/
  contact:
    name: Contact ADSB Exchange
    url: https://www.adsbexchange.com/products/enterprise-api/
  version: v2
  x-logo:
    url: https://adsbexchange.com/wp-content/uploads/ax_logo_background_api-scaled.avif
    href: '#'
servers:
- url: https://gateway.adsbexchange.com/api/aircraft/v2
tags:
- name: Geopolitical Filtering
  description: Allows filtering live data based on geopolitical boundaries, such as states/provinces, countries, regions, or even continents.
paths:
  /geospatial/country/{country}:
    get:
      tags:
      - Geopolitical Filtering
      summary: Get aircraft by country
      description: 'Returns aircraft within the boundaries of the given country.


        See below examples of how to query aircraft by country.

        Country must be specified as ISO 3166-1 alpha-2 code.

        The complete list of supported country codes can be accessed here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2


        USA:

        * `/api/aircraft/v2/geospatial/country/US`


        Canada:

        * `/api/aircraft/v2/geospatial/country/CA`'
      operationId: GetApiAircraftV2GeospatialCountry
      parameters:
      - name: country
        in: path
        required: true
        description: Country ISO 3166-1 alpha-2 code. Case-insensitive.
        schema:
          type: string
        x-position: 1
      - type: string
        name: Accept-Encoding
        in: header
        required: true
        description: The encoding type the client will accept in the response. API call must use compression.
        default: gzip
        example: gzip
      responses:
        '200':
          description: Response containing a collection of aircraft models.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AircraftCollectionResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUnauthorizedResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiForbiddenResponse'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTooManyRequestsResponse'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - X-Api-Key: []
  /geospatial/country/{country}/subdivisions:
    get:
      tags:
      - Geopolitical Filtering
      summary: Get subdivisions by country code
      description: 'Whe country code is provided, this endpoint will return a list of state/province subdivisions for the given country.


        This endpoint is complimentary to `/geospatial/country/{country}/subdivision/{subdivision}` endpoint.


        The complete list of supported country codes and states/provinces can be accessed here:

        * Countries: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

        * States/Provinces: https://en.wikipedia.org/wiki/ISO_3166-2


        For example, to get a list of subdivisions for the United States you would call:

        ```

        GET /api/aircraft/v2/geospatial/country/US/subdivisions

        ```

        and expect a response with a collection of subdivisions:

        ```json

        {

        "country": "us",

        "subdivisions": [

        {

        "name": "Washington",

        "iso_a2": "US",

        "iso_3166_2": "US-WA",

        "adm1_code": "USA-3519",

        "name_alt": "WA|Wash.",

        "region": "West"

        },

        ...

        ]

        }

        ```

        and in requests to `/geospatial/country/{country}/subdivision/{subdivision}` endpoint you would use `iso_3166_2` code as a subdivision identifier.'
      operationId: GetApiAircraftV2GeospatialCountrySubdivisions
      parameters:
      - name: country
        in: path
        required: true
        description: Country ISO 3166-1 alpha-2 code. Case-insensitive.
        schema:
          type: string
        x-position: 1
      - type: string
        name: Accept-Encoding
        in: header
        required: true
        description: The encoding type the client will accept in the response. API call must use compression.
        default: gzip
        example: gzip
      responses:
        '200':
          description: Response containing a collection of subdivisions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoboundaryCountrySubdivisionsResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUnauthorizedResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiForbiddenResponse'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTooManyRequestsResponse'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - X-Api-Key: []
  /geospatial/country/{country}/subdivision/{subdivision}:
    get:
      tags:
      - Geopolitical Filtering
      summary: 'Get aircraft by country subdivision: state/province'
      description: 'Returns aircraft within the boundaries of the given country''s subdivision: state or province.


        * Country must be specified as ISO 3166-1 alpha-2 code.

        * State/province must be specified as ISO 3166-2 code. You can omit the country code prefix.

        Both of the arguments are case-insensitive.


        See below examples of how to query aircraft by country and state/province.


        USA - California:

        * `/api/aircraft/v2/geospatial/country/US/subdivision/CA`

        * `/api/aircraft/v2/geospatial/country/US/subdivision/US-CA`


        Canada - British Columbia:

        * `/api/aircraft/v2/geospatial/country/CA/subdivision/BC`

        * `/api/aircraft/v2/geospatial/country/CA/subdivision/CA-BC`


        France - Paris:

        * `/api/aircraft/v2/geospatial/country/FR/subdivision/75`

        * `/api/aircraft/v2/geospatial/country/FR/subdivision/FR-75`


        The complete list of supported country codes and states/provinces can be accessed here:

        * Countries: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

        * States/Provinces: https://en.wikipedia.org/wiki/ISO_3166-2


        You can get supported states/provinces by making GET request to

        `/geospatial/country/{country}/subdivisions` endpoint.'
      operationId: GetApiAircraftV2GeospatialCountrySubdivision
      parameters:
      - name: country
        in: path
        required: true
        description: Country ISO 3166-1 alpha-2 code. Case-insensitive.
        schema:
          type: string
        x-position: 1
      - name: subdivision
        in: path
        required: true
        description: Subdivision (state/province) ISO_3166-2 code. You can omit the country code prefix. Case-insensitive.
        schema:
          type: string
        x-position: 2
      - type: string
        name: Accept-Encoding
        in: header
        required: true
        description: The encoding type the client will accept in the response. API call must use compression.
        default: gzip
        example: gzip
      responses:
        '200':
          description: Response containing a collection of aircraft models.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AircraftCollectionResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUnauthorizedResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiForbiddenResponse'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTooManyRequestsResponse'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - X-Api-Key: []
  /geospatial/region/{region}:
    get:
      tags:
      - Geopolitical Filtering
      summary: Get aircraft by geographical region
      description: 'Returns aircraft within the boundaries of the given geographical region.


        Supported regions:

        * Northern/Eastern/Southern/Western Europe

        * North/Central/South America

        * Central/East/South-East/South/West Asia

        * North/Middle/East/South/West Africa

        * Australia and New Zealand

        * Caribbean

        * Melanesia

        * Micronesia

        * Polynesia


        To filter by ''North America'' use pure text value from the list above. Remove spaces, or URL-encode them. Case-insensitive.


        * `/api/aircraft/v2/geospatial/region/NorthAmerica`

        * `/api/aircraft/v2/geospatial/region/North%20America`


        To filter by ''South-East Asia'':


        * `/api/aircraft/v2/geospatial/region/south-eastasia`

        * `/api/aircraft/v2/geospatial/region/South-East%20Asia`'
      operationId: GetApiAircraftV2GeospatialRegion
      parameters:
      - name: region
        in: path
        required: true
        description: Name of the geographical region from the list above. Case-insensitive.
        schema:
          type: string
        x-position: 1
      - type: string
        name: Accept-Encoding
        in: header
        required: true
        description: The encoding type the client will accept in the response. API call must use compression.
        default: gzip
        example: gzip
      responses:
        '200':
          description: Response containing a collection of aircraft models.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AircraftCollectionResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUnauthorizedResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiForbiddenResponse'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTooManyRequestsResponse'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - X-Api-Key: []
  /geospatial/continent/{continent}:
    get:
      tags:
      - Geopolitical Filtering
      summary: Get aircraft by continent
      description: 'Returns aircraft within the boundaries of the given continent.


        Supported continents:

        * Americas

        * Africa

        * Asia

        * Europe

        * Oceania

        * Antarctica


        To filter by continent use pure text value from the list above.


        Examples:

        * `/api/aircraft/v2/geospatial/continent/Europe`

        * `/api/aircraft/v2/geospatial/continent/Antarctica`'
      operationId: GetApiAircraftV2GeospatialContinent
      parameters:
      - name: continent
        in: path
        required: true
        description: Name of the continent from the list above. Case-insensitive.
        schema:
          type: string
        x-position: 1
      - type: string
        name: Accept-Encoding
        in: header
        required: true
        description: The encoding type the client will accept in the response. API call must use compression.
        default: gzip
        example: gzip
      responses:
        '200':
          description: Response containing a collection of aircraft models.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AircraftCollectionResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUnauthorizedResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiForbiddenResponse'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTooManyRequestsResponse'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - X-Api-Key: []
components:
  schemas:
    AircraftCollectionResponse:
      type: object
      description: Response envelope for the multiple aircraft endpoint.
      additionalProperties: false
      properties:
        ac:
          type: array
          description: List of aircraft with all available information.
          items:
            $ref: '#/components/schemas/AircraftSingleResponse'
        msg:
          type: string
          description: Message indicating the status of the request overall.
        now:
          type: integer
          description: Unix timestamp of the current UTC time on the server (ms).
          format: int64
        total:
          type: integer
          description: The number of aircraft in the response.
          format: int32
        ctime:
          type: integer
          description: Unix timestamp (ms) of when the underlying data was last updated.
          format: int64
        ptime:
          type: integer
          description: Time taken on server to process the request (ms).
          format: int64
    ProblemDetails:
      type: object
      additionalProperties: {}
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
    GeoboundaryCountrySubdivisionsResponse:
      type: object
      description: Response from the geoboundary endpoint containing country subdivisions.
      additionalProperties: false
      properties:
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
        subdivisions:
          type: array
          description: List of subdivisions for the country available in the API.
          items:
            $ref: '#/components/schemas/GeoboundaryCountrySubdivision'
    ApiUnauthorizedResponse:
      type: object
      additionalProperties: false
      properties:
        msg:
          type: string
        reason:
          type:
          - string
          - 'null'
    LastPositionDataResponse:
      type: object
      description: 'When the regular lat and lon are older than 60 seconds

        they are no longer considered valid, this will provide

        the last position and show the age for the last position.

        Aircraft will only be in the aircraft json if a position

        has been received in the last 60 seconds or if any message

        has been received in the last 30 seconds.'
      additionalProperties: false
      properties:
        lat:
          type:
          - number
          - 'null'
          format: float
        lon:
          type:
          - number
          - 'null'
          format: float
        nic:
          type:
          - integer
          - 'null'
          description: Navigation Integrity Category (2.2.3.2.7.2.6)
          format: int32
        rc:
          type:
          - integer
          - 'null'
          description: 'Radius of Containment, meters; a measure of position integrity

            derived from NIC and supplementary bits. (2.2.3.2.7.2.6, Table 2-69)'
          format: int32
        seen_pos:
          type:
          - number
          - 'null'
          description: How long ago (in seconds before “now”) the position was last updated
          format: double
    AcasResolutionAdvisoryResponse:
      type: object
      description: ACAS Resolution Advisory Class
      additionalProperties: false
      properties:
        utc:
          type:
          - string
          - 'null'
          description: UTC timestamp of the advisory.
        unix_timestamp:
          type:
          - number
          - 'null'
          description: Unix timestamp.
          format: double
        bytes:
          type:
          - string
          - 'null'
          description: Advisory bytes as a string.
        ARA:
          type:
          - string
          - 'null'
          description: Advisory ARA field.
        RAT:
          type:
          - string
          - 'null'
          description: Advisory RAT field.
        MTE:
          type:
          - string
          - 'null'
          description: Advisory MTE field.
        RAC:
          type:
          - string
          - 'null'
          description: Advisory RAC field.
        advisory_complement:
          type:
          - string
          - 'null'
          description: Advisory complement description.
        advisory:
          type:
          - string
          - 'null'
          description: Advisory description.
        TTI:
          type:
          - string
          - 'null'
          description: TTI field.
        threat_id_hex:
          type:
          - string
          - 'null'
          description: Threat ID in hexadecimal.
    GeoboundaryCountrySubdivision:
      type: object
      description: Represents the response from the geoboundary endpoint.
      additionalProperties: false
      properties:
        name:
          type: string
          description: 'Name of the country subdivision.

            Example: California'
        iso_a2:
          type: string
          description: 'ISO 3166-1 alpha-2 country code.

            Example: US'
        iso_3166_2:
          type: string
          description: 'ISO 3166-2 country subdivision code.

            Example: US-CA (for California)'
        adm1_code:
          type:
          - string
          - 'null'
          description: 'ADM1 code.

            Example: USA-3521'
        name_alt:
          type:
          - string
          - 'null'
          description: 'Alternative name of the country subdivision.

            Example: CA|Calif.|Cal.'
        region:
          type:
          - string
          - 'null'
          description: 'Name of the region.

            Example: West'
    ApiTooManyRequestsResponse:
      type: object
      additionalProperties: false
      properties:
        message:
          type: string
    ApiForbiddenResponse:
      type: object
      additionalProperties: false
      properties:
        msg:
          type: string
        reason:
          type:
          - string
          - 'null'
    AircraftSingleResponse:
      type: object
      description: Full aircraft model with all available information.
      additionalProperties: false
      properties:
        hex:
          type: string
          description: The ICAO 24-bit address (hex) of the aircraft.
        type:
          type:
          - string
          - 'null'
          description: The type of message (e.g., adsb_icao, tisb_icao, etc.).
        flight:
          type:
          - string
          - 'null'
          description: The flight number or callsign.
        r:
          type:
          - string
          - 'null'
          description: Registration or tail number.
        t:
          type:
          - string
          - 'null'
          description: Aircraft type (e.g., B38M for Boeing 737 MAX 8).
        dbFlags:
          type:
          - integer
          - 'null'
          description: Bitfield for certain database flags, below and must be a bitwise and … check the documentation for your programming language
          example: "  military = dbFlags & 1;\n  interesting = dbFlags & 2;\n  PIA = dbFlags & 4;\n  LADD = dbFlags & 8;"
        alt_baro:
          description: Barometric altitude in feet.
        alt_geom:
          type:
          - number
          - 'null'
          description: Geometric altitude in feet.
          format: float
        gs:
          type:
          - number
          - 'null'
          description: Ground speed in knots.
          format: float
        ias:
          type:
          - number
          - 'null'
          description: Indicated airspeed in knots
          format: float
        tas:
          type:
          - number
          - 'null'
          description: True airspeed in knots.
          format: float
        mach:
          type:
          - number
          - 'null'
          description: Mach number (speed as a fraction of the speed of sound).
          format: float
        wd:
          type:
          - integer
          - 'null'
          description: Wind direction in degrees.
        ws:
          type:
          - integer
          - 'null'
          description: Wind speed in knots.
        oat:
          type:
          - integer
          - 'null'
          description: Outer/Static air temperature (OAT), typically somewhat inaccurate at lower altitudes.
        tat:
          type:
          - integer
          - 'null'
          description: Total air temperature (TAT), typically somewhat inaccurate at lower altitudes.
        track:
          type:
          - number
          - 'null'
          description: Aircraft track over the ground in degrees.
          format: float
        track_rate:
          type:
          - number
          - 'null'
          description: Rate of change of the track in degrees per second.
          format: float
        roll:
          type:
          - number
          - 'null'
          description: Aircraft roll angle in degrees.
          format: float
        mag_heading:
          type:
          - number
          - 'null'
          description: Magnetic heading in degrees.
          format: float
        true_heading:
          type:
          - number
          - 'null'
          description: True heading in degrees.
          format: float
        baro_rate:
          type:
          - integer
          - 'null'
          description: Barometric vertical rate (climb or descent) in feet per minute.
          format: int32
        geom_rate:
          type:
          - integer
          - 'null'
          description: Geometric vertical rate (climb or descent) in feet per minute.
          format: int32
        squawk:
          type:
          - string
          - 'null'
          description: Transponder squawk code.
        emergency:
          type:
          - string
          - 'null'
          description: Emergency code (if applicable).
        category:
          type:
          - string
          - 'null'
          description: Aircraft category based on size and weight.
        nav_qnh:
          type:
          - number
          - 'null'
          description: QNH setting (altimeter pressure setting) in hPa.
          format: float
        nav_altitude_mcp:
          type:
          - integer
          - 'null'
          description: MCP (Mode Control Panel) altitude setting in feet.
        nav_altitude_fms:
          type:
          - integer
          - 'null'
          description: Selected altitude from the Flight Management System (FMS) in feet.
        nav_heading:
          type:
          - number
          - 'null'
          description: MCP heading setting in degrees.
          format: float
        nav_modes:
          type:
          - array
          - 'null'
          description: 'Navigation modes: autopilot, vnav, althold, approach, lnav, tcas'
          items:
            type: string
        rr_lat:
          type:
          - number
          - 'null'
          description: Rough estimated latitude based on receiver's position.
          format: float
        rr_lon:
          type:
          - number
          - 'null'
          description: Rough estimated longitude based on receiver's position.
          format: float
        lastPosition:
          description: Last known position if lat/lon are older than 60 seconds.
          oneOf:
          - $ref: '#/components/schemas/LastPositionDataResponse'
        gpsOkBefore:
          type:
          - number
          - 'null'
          description: Indicator of whether GPS was working well before degradation.
          format: double
        gpsOkLat:
          type:
          - number
          - 'null'
          description: Indicator of whether GPS was working well before degradation - latitude.
          format: double
        gpsOkLon:
          type:
          - number
          - 'null'
          description: Indicator of whether GPS was working well before degradation - longitude.
          format: double
        lat:
          type:
          - number
          - 'null'
          description: Latitude of the aircraft.
          format: float
        lon:
          type:
          - number
          - 'null'
          description: Longitude of the aircraft.
          format: float
        nic:
          type:
          - integer
          - 'null'
          description: Navigation Integrity Category.
          format: int32
        rc:
          type:
          - integer
          - 'null'
          description: Containment Radius of Accuracy in meters.
        seen_pos:
          type:
          - number
          - 'null'
          description: Time since the last positional update in seconds.
          format: float
        version:
          type:
          - integer
          - 'null'
          description: ADS-B version.
          format: int32
        nic_baro:
          type:
          - integer
          - 'null'
          description: Barometric NIC (Navigation Integrity Category).
        nac_p:
          type:
          - integer
          - 'null'
          description: Navigation Accuracy Category for Position.
        nac_v:
          type:
          - integer
          - 'null'
          description: Navigation Accuracy Category for Velocity.
        sil:
          type:
          - integer
          - 'null'
          description: Source Integrity Level.
        sil_type:
          type:
          - string
          - 'null'
          description: Source Integrity Level type (e.g., per hour or per sample).
        gva:
          type:
          - integer
          - 'null'
          description: Geometric Vertical Accuracy.
        sda:
          type:
          - integer
          - 'null'
          description: System Design Assurance.
        alert:
          type:
          - integer
          - 'null'
          description: Alert status (whether the transponder is indicating an alert).
        spi:
          type:
          - integer
          - 'null'
          description: Special Position Identification (SPI) status.
        mlat:
          type:
          - array
          - 'null'
          description: List of fields derived from MLAT data (e.g., "lat", "lon", "nic", "rc").
          items:
            type: string
        tisb:
          type:
          - array
          - 'null'
          description: List of fields derived from TIS-B data (e.g., "gs", "lat", "lon", "nic", "rc", "nac_p", "sil", "sil_type").
          items:
            type: string
        messages:
          type:
          - integer
          - 'null'
          description: The number of messages received from the aircraft.
          format: int64
        seen:
          type:
          - number
          - 'null'
          description: Time since the last message was received, in seconds.
          format: float
        rssi:
          type:
          - number
          - 'null'
          description: Signal strength in dBFS.
          format: float
        acas_ra:
          description: ACAS Resolution Advisory data (experimental, subject to change).
          oneOf:
          - $ref: '#/components/schemas/AcasResolutionAdvisoryResponse'
        now:
          type:
          - integer
          - 'null'
          description: Unix milliseconds timestamp of the time the data was put into the cache.
          format: int64
        geometries:
          type:
          - array
          - 'null'
          description: 'Contains caller-supplied collection of properties (up to 5) per matched geometry.

            Properties are propagated from each geometry object in the filter request.'
          items:
            type: object
            additionalProperties:
              type: string
  securitySchemes:
    X-Api-Key:
      type: apiKey
      description: Provide your API key via x-api-key header to access the API.
      name: x-api-key
      in: header
x-generator: NSwag v14.1.0.0 (NJsonSchema v11.0.2.0 (Newtonsoft.Json v13.0.0.0))