openapi: 3.0.0
info:
title: ADSB Exchange Geopolitical Filtering API
description: "The ADSB Exchange API provides real-time access to live global flight data,\nenabling retrieval of detailed information on aircraft positions, flight events, historical trace files,\nand many more aviation metrics. <br /><br />\nKnown for its accurate data, ADSB Exchange API is ideal\nfor aviation tracking applications, research, and analytics, offering extensive coverage powered by a\nglobal network of ADS-B and MLAT receivers. <br /><br />\nThis documentation is available in <a href=\"/api/aircraft/v2/docs\">ReDoc</a> and <a href=\"/api/aircraft/v2/docs/swagger\">Swagger</a> formats.\n<p>\n<b>Important developer notes:</b><br />\n<ul>\n <li>When designing API client, please ensure that all requests include the 'Accept-Encoding' header with 'gzip' value.</li>\n <li>When property values are not available, they will be omitted from the response object overall.</li>\n <li>When parsing JSON response do not hard-code the order of properties. Use property names to access values.</li>\n <li>We will never remove or rename properties. However, we may add new properties. Please ensure your code is resilient to new additive properties on the response objects.</li>\n</ul>\n</p>"
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.
All endpoints support ISO 3166-1 alpha-2 country codes and ISO 3166-2 subdivision (states/provinces) codes.
<br /><br />
World boundaries are based on <a href="https://public.opendatasoft.com/explore/dataset/world-administrative-boundaries/map/" target="_blank">OpenDataSoft</a> dataset.
<b>Attribution:</b><br />
This API includes data from <a href="https://marineregions.org/" target="_blank">Marine Regions</a>, licensed under
<a href="https://creativecommons.org/licenses/by/4.0/" target="_blank">Creative Commons Attribution 4.0 International (CC BY 4.0)</a>.<br />
<i>Flanders Marine Institute (2023). Maritime Boundaries Geodatabase, version 12. DOI: <a href="https://doi.org/10.14284/632" target="_blank">10.14284/632</a></i>'
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.\n\nThis endpoint is complimentary to `/geospatial/country/{country}/subdivision/{subdivision}` endpoint.\n\nThe complete list of supported country codes and states/provinces can be accessed here:\n* Countries: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2\n* States/Provinces: https://en.wikipedia.org/wiki/ISO_3166-2\n\n\nFor example, to get a list of subdivisions for the United States you would call:\n```\nGET /api/aircraft/v2/geospatial/country/US/subdivisions\n```\nand expect a response with a collection of subdivisions:\n```json\n{\n \"country\": \"us\",\n \"subdivisions\": [\n {\n \"name\": \"Washington\",\n \"iso_a2\": \"US\",\n \"iso_3166_2\": \"US-WA\",\n \"adm1_code\": \"USA-3519\",\n \"name_alt\": \"WA|Wash.\",\n \"region\": \"West\"\n },\n ...\n ]\n}\n```\nand 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.\n\n* Country must be specified as ISO 3166-1 alpha-2 code.\n* State/province must be specified as ISO 3166-2 code. You can omit the country code prefix.\nBoth of the arguments are case-insensitive.\n \nSee below examples of how to query aircraft by country and state/province.\n \nUSA - California:\n* `/api/aircraft/v2/geospatial/country/US/subdivision/CA`\n* `/api/aircraft/v2/geospatial/country/US/subdivision/US-CA`\n \nCanada - British Columbia:\n* `/api/aircraft/v2/geospatial/country/CA/subdivision/BC`\n* `/api/aircraft/v2/geospatial/country/CA/subdivision/CA-BC`\n \nFrance - Paris:\n* `/api/aircraft/v2/geospatial/country/FR/subdivision/75`\n* `/api/aircraft/v2/geospatial/country/FR/subdivision/FR-75`\n\n\nThe complete list of supported country codes and states/provinces can be accessed here:\n* Countries: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2\n* States/Provinces: https://en.wikipedia.org/wiki/ISO_3166-2\n\nYou can get supported states/provinces by making GET request to\n`/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.\n\nSupported regions:\n* Northern/Eastern/Southern/Western Europe\n* North/Central/South America\n* Central/East/South-East/South/West Asia\n* North/Middle/East/South/West Africa\n* Australia and New Zealand\n* Caribbean\n* Melanesia\n* Micronesia\n* Polynesia\n\n\nTo filter by 'North America' use pure text value from the list above. Remove spaces, or URL-encode them. Case-insensitive.\n \n* `/api/aircraft/v2/geospatial/region/NorthAmerica`\n* `/api/aircraft/v2/geospatial/region/North%20America`\n\n\nTo filter by 'South-East Asia':\n \n* `/api/aircraft/v2/geospatial/region/south-eastasia`\n* `/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:
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
description: 'ADM1 code.
Example: USA-3521'
nullable: true
name_alt:
type: string
description: 'Alternative name of the country subdivision.
Example: CA|Calif.|Cal.'
nullable: true
region:
type: string
description: 'Name of the region.
Example: West'
nullable: true
ApiTooManyRequestsResponse:
type: object
additionalProperties: false
properties:
message:
type: string
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
description: The type of message (e.g., adsb_icao, tisb_icao, etc.).
nullable: true
flight:
type: string
description: The flight number or callsign.
nullable: true
r:
type: string
description: Registration or tail number.
nullable: true
t:
type: string
description: Aircraft type (e.g., B38M for Boeing 737 MAX 8).
nullable: true
dbFlags:
type: integer
description: Bitfield for certain database flags, below and must be a bitwise and … check the documentation for your programming language
nullable: true
example: " military = dbFlags & 1;\n interesting = dbFlags & 2;\n PIA = dbFlags & 4;\n LADD = dbFlags & 8;"
alt_baro:
description: Barometric altitude in feet.
nullable: true
alt_geom:
type: number
description: Geometric altitude in feet.
format: float
nullable: true
gs:
type: number
description: Ground speed in knots.
format: float
nullable: true
ias:
type: number
description: Indicated airspeed in knots
format: float
nullable: true
tas:
type: number
description: True airspeed in knots.
format: float
nullable: true
mach:
type: number
description: Mach number (speed as a fraction of the speed of sound).
format: float
nullable: true
wd:
type: integer
description: Wind direction in degrees.
nullable: true
ws:
type: integer
description: Wind speed in knots.
nullable: true
oat:
type: integer
description: Outer/Static air temperature (OAT), typically somewhat inaccurate at lower altitudes.
nullable: true
tat:
type: integer
description: Total air temperature (TAT), typically somewhat inaccurate at lower altitudes.
nullable: true
track:
type: number
description: Aircraft track over the ground in degrees.
format: float
nullable: true
track_rate:
type: number
description: Rate of change of the track in degrees per second.
format: float
nullable: true
roll:
type: number
description: Aircraft roll angle in degrees.
format: float
nullable: true
mag_heading:
type: number
description: Magnetic heading in degrees.
format: float
nullable: true
true_heading:
type: number
description: True heading in degrees.
format: float
nullable: true
baro_rate:
type: integer
description: Barometric vertical rate (climb or descent) in feet per minute.
format: int32
nullable: true
geom_rate:
type: integer
description: Geometric vertical rate (climb or descent) in feet per minute.
format: int32
nullable: true
squawk:
type: string
description: Transponder squawk code.
nullable: true
emergency:
type: string
description: Emergency code (if applicable).
nullable: true
category:
type: string
description: Aircraft category based on size and weight.
nullable: true
nav_qnh:
type: number
description: QNH setting (altimeter pressure setting) in hPa.
format: float
nullable: true
nav_altitude_mcp:
type: integer
description: MCP (Mode Control Panel) altitude setting in feet.
nullable: true
nav_altitude_fms:
type: integer
description: Selected altitude from the Flight Management System (FMS) in feet.
nullable: true
nav_heading:
type: number
description: MCP heading setting in degrees.
format: float
nullable: true
nav_modes:
type: array
description: 'Navigation modes: autopilot, vnav, althold, approach, lnav, tcas'
nullable: true
items:
type: string
rr_lat:
type: number
description: Rough estimated latitude based on receiver's position.
format: float
nullable: true
rr_lon:
type: number
description: Rough estimated longitude based on receiver's position.
format: float
nullable: true
lastPosition:
description: Last known position if lat/lon are older than 60 seconds.
nullable: true
oneOf:
- $ref: '#/components/schemas/LastPositionDataResponse'
gpsOkBefore:
type: number
description: Indicator of whether GPS was working well before degradation.
format: double
nullable: true
gpsOkLat:
type: number
description: Indicator of whether GPS was working well before degradation - latitude.
format: double
nullable: true
gpsOkLon:
type: number
description: Indicator of whether GPS was working well before degradation - longitude.
format: double
nullable: true
lat:
type: number
description: Latitude of the aircraft.
format: float
nullable: true
lon:
type: number
description: Longitude of the aircraft.
format: float
nullable: true
nic:
type: integer
description: Navigation Integrity Category.
format: int32
nullable: true
rc:
type: integer
description: Containment Radius of Accuracy in meters.
nullable: true
seen_pos:
type: number
description: Time since the last positional update in seconds.
format: float
nullable: true
version:
type: integer
description: ADS-B version.
format: int32
nullable: true
nic_baro:
type: integer
description: Barometric NIC (Navigation Integrity Category).
nullable: true
nac_p:
type: integer
description: Navigation Accuracy Category for Position.
nullable: true
nac_v:
type: integer
description: Navigation Accuracy Category for Velocity.
nullable: true
sil:
type: integer
description: Source Integrity Level.
nullable: true
sil_type:
type: string
description: Source Integrity Level type (e.g., per hour or per sample).
nullable: true
gva:
type: integer
description: Geometric Vertical Accuracy.
nullable: true
sda:
type: integer
description: System Design Assurance.
nullable: true
alert:
type: integer
description: Alert status (whether the transponder is indicating an alert).
nullable: true
spi:
type: integer
description: Special Position Identification (SPI) status.
nullable: true
mlat:
type: array
description: List of fields derived from MLAT data (e.g., "lat", "lon", "nic", "rc").
nullable: true
items:
type: string
tisb:
type: array
description: List of fields derived from TIS-B data (e.g., "gs", "lat", "lon", "nic", "rc", "nac_p", "sil", "sil_type").
nullable: true
items:
type: string
messages:
type: integer
description: The number of messages received from the aircraft.
format: int64
nullable: true
seen:
type: number
description: Time since the last message was received, in seconds.
format: float
nullable: true
rssi:
type: number
description: Signal strength in dBFS.
format: float
nullable: true
acas_ra:
description: ACAS Resolution Advisory data (experimental, subject to change).
nullable: true
oneOf:
- $ref: '#/components/schemas/AcasResolutionAdvisoryResponse'
now:
type: integer
description: Unix milliseconds timestamp of the time the data was put into the cache.
format: int64
nullable: true
geometries:
type: array
description: 'Contains caller-supplied collection of properties (up to 5) per matched geometry.
Properties are propagated from each geometry object in the filter request.'
nullable: true
items:
type: object
additionalProperties:
type: string
ApiUnauthorizedResponse:
type: object
additionalProperties: false
properties:
msg:
type: string
reason:
type: string
nullable: true
ApiForbiddenResponse:
type: object
additionalProperties: false
properties:
msg:
type: string
reason:
type: string
nullable: true
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
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
format: float
nullable: true
lon:
type: number
format: float
nullable: true
nic:
type: integer
description: Navigation Integrity Category (2.2.3.2.7.2.6)
format: int32
nullable: true
rc:
type: integer
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
nullable: true
seen_pos:
type: number
description: How long ago (in seconds before “now”) the position was last updated
format: double
nullable: true
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'
AcasResolutionAdvisoryResponse:
type: object
description: ACAS Resolution Advisory Class
additionalProperties: false
properties:
utc:
type: string
description: UTC timestamp of the advisory.
nullable: true
unix_timestamp:
type: number
description: Unix timestamp.
format: double
nullable: true
bytes:
type: string
description: Advisory bytes as a string.
nullable: true
ARA:
type: string
description: Advisory ARA field.
nullable: true
RAT:
type: string
description: Advisory RAT field.
nullable: true
MTE:
type: string
description: Advisory MTE field.
nullable: true
RAC:
type: string
description: Advisory RAC field.
nullable: true
advisory_complement:
type: string
description: Advisory complement description.
nullable: true
advisory:
type: string
description: Advisory description.
nullable: true
TTI:
type: string
description: TTI field.
nullable: true
threat_id_hex:
type: string
description: Threat ID in hexadecimal.
nullable: true
ProblemDetails:
type: object
additionalProperties:
nullable: true
properties:
type:
type: string
nullable: true
title:
type: string
nullable: true
status:
type: integer
format: int32
nullable: true
detail:
type: string
nullable: true
instance:
type: string
nullable: true
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))