ADS-B Exchange Traces API
Endpoints provide access to historical trace files for an aircraft.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/adsbexchange-traces-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: ADSB Exchange Traces 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: Traces
description: Endpoints provide access to historical trace files for an aircraft.
paths:
/traces/{folder}/{jsonFile}:
get:
tags:
- Traces
summary: Get recent trace file
description: 'Returns the trace file for the aircraft with the specified ICAO code.
The trace file contains aircraft position history starting 00:00 UTC today.
Must begin with ''trace_recent_'' or ''trace_full_'' and end with ''.json''.
Folder name must be the last 2 characters of the aircraft ICAO code.
Example: to request trace file for aircraft with ICAO code ''A1B2C3'':
```
GET /api/aircraft/v2/traces/c3/trace_recent_a1b2c3.json
```
The trace file is a JSON file with the following structure:
```
{
icao: "a1b2c3", // hex id of the aircraft
timestamp: 1609275898.495, // unix timestamp in seconds since epoch (1970)
trace: [
[ seconds after timestamp,
lat,
lon,
altitude in ft or "ground" or null,
ground speed in knots or null,
track in degrees or null, (if altitude == "ground", this will be true heading instead of track)
flags as a bitfield: (use bitwise and to extract data)
(flags & 1 > 0): position is stale (no position received for 20 seconds before this one)
(flags & 2 > 0): start of a new leg (tries to detect a separation point between landing and takeoff that separates flights)
(flags & 4 > 0): vertical rate is geometric and not barometric
(flags & 8 > 0): altitude is geometric and not barometric
,
vertical rate in fpm or null,
aircraft object with extra details or null (see aircraft.json documentation, note that not all fields are present as lat and lon for example already in the values above),
// the following fields only in files generated 2022 and later:
type / source of this position or null,
geometric altitude or null,
geometric vertical rate or null,
indicated airspeed or null,
roll angle or null
],
[next entry like the one before],
[next entry like the one before],
]
}
```
Example of the response:
```
{
"icao":"a1b2c3",
"r":"N11Y22",
"t":"P123",
"dbFlags":0,
"desc":"Gulfstream G650",
"ownOp":"SOME CORP",
"year":"2021",
"timestamp": 1712275200.000,
"trace":[
[76863.35,41.279114,-70.128967,2500,118.4,326.7,5,704,{"type":"adsr_icao","track":326.71,"geom_rate":704,"nic":8,"rc":186,"nac_v":0,"alert":0,"spi":0},"adsr_icao",null,704,null,null],
[76870.59,41.282455,-70.131775,2600,119.0,328.0,4,384,null,"adsr_icao",2150,384,null,null],
[76877.88,41.286804,-70.135376,2700,117.7,328.2,4,640,null,"adsr_icao",2250,640,null,null],
[76885.92,41.290512,-70.138489,2800,118.5,328.5,4,448,null,"adsr_icao",2350,448,null,null],
...
]
}
```'
operationId: GetApiAircraftV2Traces
parameters:
- name: folder
in: path
required: true
description: Last 2 characters of ICAO code.
schema:
type: string
x-position: 1
- name: jsonFile
in: path
required: true
description: Name of the JSON file. Must be in the format 'trace_[recent|full]_{ICAO}.json'.
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: JSON response with the contents of the trace file.
content:
application/json:
schema:
$ref: '#/components/schemas/TraceResponse'
'402':
description: Payment Required
content:
application/json:
schema:
$ref: '#/components/schemas/ApiUnauthorizedResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiForbiddenResponse'
'404':
description: Trace Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/TraceNotFoundResponse'
'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: []
/traces-hist/{year}/{month}/{day}/traces/{folder}/{jsonFile}:
get:
tags:
- Traces
summary: Get historical trace file
description: 'Returns the trace file for the aircraft with the specified ICAO code.
The trace file contains aircraft position history before UTC today.
For getting the trace file for the current day, use the ''Get recent trace file'' endpoint.
File name must begin with ''trace_full_'' and end with ''.json''.
Folder name must be the last 2 characters of the aircraft ICAO code.
Traces are available from January 1st, 2016 and later.
Example: to request trace file for aircraft with ICAO code ''A1B2C3'' for January 22, 2023:
```
GET /api/aircraft/v2/traces-hist/2023/01/22/traces/c3/trace_full_a1b2c3.json
```
The trace file is a JSON file with the following structure:
```
{
icao: "a1b2c3", // hex id of the aircraft
timestamp: 1609275898.495, // unix timestamp in seconds since epoch (1970)
trace: [
[ seconds after timestamp,
lat,
lon,
altitude in ft or "ground" or null,
ground speed in knots or null,
track in degrees or null, (if altitude == "ground", this will be true heading instead of track)
flags as a bitfield: (use bitwise and to extract data)
(flags & 1 > 0): position is stale (no position received for 20 seconds before this one)
(flags & 2 > 0): start of a new leg (tries to detect a separation point between landing and takeoff that separates flights)
(flags & 4 > 0): vertical rate is geometric and not barometric
(flags & 8 > 0): altitude is geometric and not barometric
,
vertical rate in fpm or null,
aircraft object with extra details or null (see aircraft.json documentation, note that not all fields are present as lat and lon for example already in the values above),
// the following fields only in files generated 2022 and later:
type / source of this position or null,
geometric altitude or null,
geometric vertical rate or null,
indicated airspeed or null,
roll angle or null
],
[next entry like the one before],
[next entry like the one before],
]
}
```
Example of the response:
```
{
"icao":"a1b2c3",
"r":"N11Y22",
"t":"P123",
"dbFlags":0,
"desc":"Gulfstream G650",
"ownOp":"SOME CORP",
"year":"2021",
"timestamp": 1712275200.000,
"trace":[
[76863.35,41.279114,-70.128967,2500,118.4,326.7,5,704,{"type":"adsr_icao","track":326.71,"geom_rate":704,"nic":8,"rc":186,"nac_v":0,"alert":0,"spi":0},"adsr_icao",null,704,null,null],
[76870.59,41.282455,-70.131775,2600,119.0,328.0,4,384,null,"adsr_icao",2150,384,null,null],
[76877.88,41.286804,-70.135376,2700,117.7,328.2,4,640,null,"adsr_icao",2250,640,null,null],
[76885.92,41.290512,-70.138489,2800,118.5,328.5,4,448,null,"adsr_icao",2350,448,null,null],
...
]
}
```'
operationId: GetApiAircraftV2TracesHistTraces
parameters:
- name: year
in: path
required: true
description: Year of the trace file.
schema:
type: string
x-position: 1
- name: month
in: path
required: true
description: Month of the trace file.
schema:
type: string
x-position: 2
- name: day
in: path
required: true
description: Day of the trace file.
schema:
type: string
x-position: 3
- name: folder
in: path
required: true
description: Last 2 characters of ICAO code.
schema:
type: string
x-position: 4
- name: jsonFile
in: path
required: true
description: Name of the JSON file. Must be in the format 'trace_full_{ICAO}.json'.
schema:
type: string
x-position: 5
- 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: JSON response with the contents of the trace file.
content:
application/json:
schema:
$ref: '#/components/schemas/TraceResponse'
'402':
description: Payment Required
content:
application/json:
schema:
$ref: '#/components/schemas/ApiUnauthorizedResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiForbiddenResponse'
'404':
description: Trace Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/TraceNotFoundResponse'
'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:
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'
ApiUnauthorizedResponse:
type: object
additionalProperties: false
properties:
msg:
type: string
reason:
type:
- string
- 'null'
ApiTooManyRequestsResponse:
type: object
additionalProperties: false
properties:
message:
type: string
ApiForbiddenResponse:
type: object
additionalProperties: false
properties:
msg:
type: string
reason:
type:
- string
- 'null'
TraceResponse:
type: object
description: Model used to represent a trace response example.
additionalProperties: false
properties:
icao:
type: string
timestamp:
type: number
format: double
trace:
type: array
items:
type: array
items: {}
TraceNotFoundResponse:
type: object
additionalProperties: false
properties:
msg:
type: string
description: Message indicating the status of the request overall.
details:
type:
- string
- 'null'
description: Message clarifying the unsuccessful response.
status:
type: integer
description: Status code indicating the status of the request overall.
format: int32
ctime:
type: integer
description: Unix timestamp of when the underlying data was last updated.
format: int64
now:
type: integer
description: Unix timestamp of the current UTC time on the server.
format: int64
ptime:
type: integer
description: Time taken on API server to process the request, in milliseconds.
format: int64
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))