FlyItalyADSB History API
Tracks: per-aircraft daily tracks, every day since 2023-03-03 except 2026-05-05 and 2026-05-06, and the first and last point of each flight from 2022-04-10; and the aircraft that flew over a place (since 2026-08-17).
Tracks: per-aircraft daily tracks, every day since 2023-03-03 except 2026-05-05 and 2026-05-06, and the first and last point of each flight from 2022-04-10; and the aircraft that flew over a place (since 2026-08-17).
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/flyitalyadsb:flyitalyadsb-history-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a 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: 3.2.0
info:
title: FlyItalyADSB History API
version: '2'
summary: Live and historical aircraft positions worldwide from the FlyItalyADSB community ADS-B/MLAT network. Commercial use allowed on every plan, Free included; the whole world in one request from the Pro plan (€49/month).
description: 'Unfiltered aircraft data (no FAA/LADD/BARR filtering; military aircraft included, many of them via MLAT) from a global network of receivers run by volunteers (about 3,200 receivers, densest in North America and Europe; any point on Earth can be queried), as readsb aircraft.json records (the same format as tar1090), plus an ADS-B Exchange v2–compatible variant at /api/aircraft/v2. PIA and LADD aircraft are flagged in the dbFlags bit field (value 4 for PIA, 8 for LADD), so your product can hide them where its market or app store requires. Every endpoint except the key signup needs an X-Api-Key; keys are self-serve (see /auth.md). Plans and limits: https://flyitalyadsb.com/data/api/#piani. The same key works on the MCP server at https://flyitalyadsb.com/mcp. The same data is also served in the ADS-B Exchange v2 format (same paths, key headers and JSON; radius in nautical miles) at https://api.flyitalyadsb.com/api/aircraft/v2, documented at https://flyitalyadsb.com/data/api/docs/adsbx-v2/. Operated by Nesso Labs S.r.l. (ISO/IEC 27001:2022, QMSCERT 160426-7).'
termsOfService: https://flyitalyadsb.com/terms/
contact:
name: Nesso Labs S.r.l. (FlyItalyADSB)
email: info@flyitalyadsb.com
url: https://flyitalyadsb.com/contact/
license:
name: 'Data: CC BY-SA 4.0'
url: https://creativecommons.org/licenses/by-sa/4.0/
servers:
- url: https://api.flyitalyadsb.com
security:
- ApiKey: []
tags:
- name: History
description: 'Tracks: per-aircraft daily tracks, every day since 2023-03-03 except 2026-05-05 and 2026-05-06, and the first and last point of each flight from 2022-04-10; and the aircraft that flew over a place (since 2026-08-17).'
paths:
/v2/history/{icao}:
get:
summary: Dates with a recorded track for one aircraft
tags:
- History
parameters:
- name: icao
in: path
required: true
description: 24-bit ICAO address, 6 hex characters.
schema:
type: string
pattern: ^[0-9a-fA-F]{6}$
responses:
'200':
description: Sorted list of dates.
headers:
X-FIA-Plan:
$ref: '#/components/headers/X-FIA-Plan'
X-FIA-Used-Month:
$ref: '#/components/headers/X-FIA-Used-Month'
content:
application/json:
schema:
$ref: '#/components/schemas/HistoryDates'
'400':
description: icao is not 6 hex characters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/Unavailable'
operationId: getV2HistoryByIcao
x-operation-id-source: derived
/v2/history/{icao}/{date}:
get:
summary: One aircraft's track for one day
description: 'readsb''s trace_full file for that aircraft and day, passed through as written. From 2022-04-10 to 2023-10-04 the archive also holds imported Virtual Radar Server data: only the first and last point of each flight ("version": "vrs-basestation-import"). From 2023-03-03 that file is returned only when there is no full track for that aircraft and day. The current day is built from readsb''s live trace files (X-History-Source live), or from the overflights store once readsb no longer has the aircraft (store: position, altitude, flags, source and callsign only); it may answer 503 while a file is being written. With since, only the points after that time, the rest of the file unchanged (X-Since-Applied: 1). https://flyitalyadsb.com/data/api/docs/endpoints/#since'
tags:
- History
parameters:
- name: icao
in: path
required: true
description: 24-bit ICAO address, 6 hex characters.
schema:
type: string
pattern: ^[0-9a-fA-F]{6}$
- name: date
in: path
required: true
description: UTC day, YYYY-MM-DD, not in the future.
schema:
type: string
format: date
- name: since
in: query
required: false
description: 'Unix time in seconds: keep only the points with timestamp + offset > since. Milliseconds, negative or non-numeric values: 400, not counted. Empty = absent.'
schema:
type: number
minimum: 0
examples:
- 1794038400
responses:
'200':
description: The trace.
headers:
X-FIA-Plan:
$ref: '#/components/headers/X-FIA-Plan'
X-FIA-Used-Month:
$ref: '#/components/headers/X-FIA-Used-Month'
X-History-Source:
description: 'Where the day was read from: `local` (the server), `r2` (the archive), `live` (today, readsb''s live trace) or `store` (today, the overflights store).'
schema:
type: string
enum:
- local
- r2
- live
- store
X-Since-Applied:
$ref: '#/components/headers/X-Since-Applied'
content:
application/json:
schema:
$ref: '#/components/schemas/Trace'
'400':
description: icao or date is malformed, the date is in the future, or since is not a Unix time in seconds.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: No trace for this aircraft on this date.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
'502':
description: The archived trace could not be read.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: 'The archive is briefly unavailable, or today''s file is being written: retry shortly.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: getV2HistoryByIcaoByDate
x-operation-id-source: derived
/v2/profile/{icao}:
get:
summary: Profile of one aircraft
description: 'Identity (registration, ICAO type, type description, year, decoded dbFlags), live status (position, callsign and position source when received now) and a history summary (first and last day with a track, days in the last 30 UTC days, total days; the same dates as /v2/history/{icao}), plus links to the public map and to a public photo page. One request. Never returns owner or operator names. No photo is embedded: Planespotters.net''s API terms forbid re-serving their photos through another API, so `photos.page` is a link to their public page, and it is null (with `withheld`) for PIA and LADD aircraft.'
tags:
- History
parameters:
- name: icao
in: path
required: true
description: 24-bit ICAO address, 6 hex characters.
schema:
type: string
pattern: ^[0-9a-fA-F]{6}$
responses:
'200':
description: The profile.
headers:
X-FIA-Plan:
$ref: '#/components/headers/X-FIA-Plan'
X-FIA-Used-Month:
$ref: '#/components/headers/X-FIA-Used-Month'
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
'400':
description: icao is not 6 hex characters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Not received now and no recorded history for this aircraft.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
description: 'Live data or the archive is briefly unavailable: retry shortly.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: getV2ProfileByIcao
x-operation-id-source: derived
/v2/overflights:
get:
summary: Aircraft that flew over a place in a time window
description: 'Every aircraft whose recorded track passed within `dist` km of the point between `from` and `to`, one entry per aircraft, sorted by the time of its closest point. Tracks are interpolated between received positions (gaps over 5 minutes are not). Covers the days since 2026-08-17, the current day up to about 10 minutes ago, and the periods not searched are listed in `coverage.gaps`. One request per call. The maximum `dist` and window depend on the plan (Free 10 km / 6 h, Starter 25 km / 24 h, others 50 km / 24 h): https://flyitalyadsb.com/data/api/#piani. Aircraft data only: registration, type, description and dbFlags, never the owner or operator.'
tags:
- History
parameters:
- name: lat
in: query
required: true
description: Latitude, decimal degrees.
schema:
type: number
minimum: -90
maximum: 90
- name: lon
in: query
required: true
description: Longitude, decimal degrees.
schema:
type: number
minimum: -180
maximum: 180
- name: dist
in: query
required: true
description: Radius in km.
schema:
type: number
exclusiveMinimum: 0
maximum: 50
- name: from
in: query
required: true
description: 'Start: ISO 8601 (UTC when there is no offset) or Unix seconds.'
schema:
type: string
examples:
- '2026-10-21T08:00:00Z'
- name: to
in: query
required: true
description: 'End, after `from`: ISO 8601 or Unix seconds. A time in the future is cut to now.'
schema:
type: string
examples:
- '2026-10-21T10:00:00Z'
- name: max_alt_ft
in: query
required: false
description: Only the part of each track at or below this altitude (feet); positions without altitude are left out.
schema:
type: number
minimum: 0
maximum: 100000
- name: limit
in: query
required: false
description: At most this many aircraft.
schema:
type: integer
minimum: 1
maximum: 500
default: 100
responses:
'200':
description: The overflights, with what was searched.
headers:
X-FIA-Plan:
$ref: '#/components/headers/X-FIA-Plan'
X-FIA-Used-Month:
$ref: '#/components/headers/X-FIA-Used-Month'
content:
application/json:
schema:
$ref: '#/components/schemas/Overflights'
'400':
description: A parameter is missing or malformed, `to` is not after `from`, or the circle contains a pole.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: '`dist` or the window is above the plan''s maximum (the body carries max_dist_km and max_window_hours).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
description: 'Too many searches at once, or the index is briefly unavailable: retry shortly (Retry-After).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: getV2Overflights
x-operation-id-source: derived
components:
schemas:
HistoryDates:
type: object
required:
- icao
- count
- dates
properties:
icao:
type: string
count:
type: integer
dates:
type: array
items:
type: string
format: date
archive_unavailable:
type: boolean
description: 'Present when the archive could not be listed: only recent days are included.'
Overflights:
type: object
required:
- count
- truncated
- coverage
- overflights
properties:
lat:
type: number
lon:
type: number
dist_km:
type: number
from:
type: string
format: date-time
to:
type: string
format: date-time
max_alt_ft:
type:
- number
- 'null'
count:
type: integer
truncated:
type: boolean
description: More passes exist than were returned.
complete_until:
type:
- string
- 'null'
format: date-time
description: 'When truncated: every pass whose closest_time is before this is listed. Ask again from here.'
coverage:
type: object
properties:
complete:
type: boolean
gaps:
type: array
description: Periods NOT searched (not indexed yet, not covered, or tracks that could not be read).
items:
type: object
properties:
from:
type: string
format: date-time
to:
type: string
format: date-time
reason:
type: string
candidates:
type: integer
description: Aircraft examined.
overflights:
type: array
items:
$ref: '#/components/schemas/Overflight'
Overflight:
type: object
properties:
icao:
type: string
r:
type:
- string
- 'null'
description: Registration.
t:
type:
- string
- 'null'
description: ICAO type code.
desc:
type:
- string
- 'null'
dbFlags:
type: integer
callsigns:
type: array
items:
type: string
closest_time:
type: string
format: date-time
closest_ts:
type: number
description: Unix seconds.
closest_km:
type: number
closest_alt_ft:
oneOf:
- type: number
- const: ground
- type: 'null'
min_alt_ft:
oneOf:
- type: number
- const: ground
- type: 'null'
description: Lowest altitude inside the circle.
entered:
type: string
format: date-time
left:
type: string
format: date-time
passes:
type: integer
description: Separate times it entered the circle.
positions:
type: integer
description: Received positions inside the circle; 0 = interpolated between positions outside it.
source:
type: string
enum:
- adsb
- mlat
- tisb
- other
description: Source of the closest position.
sources:
type: array
items:
type: string
history:
type: array
items:
type: string
description: The /v2/history paths of the days read.
Trace:
type: object
description: 'readsb trace_full JSON: icao, timestamp, and trace (array of points relative to timestamp), plus aircraft metadata.'
properties:
icao:
type: string
timestamp:
type: number
trace:
type: array
items:
type: array
additionalProperties: true
Error:
type: object
required:
- error
properties:
error:
type: string
code:
type: string
help:
type: string
format: uri
description: 'On 401, 403 and 429: the FAQ answer for this error.'
additionalProperties: true
Profile:
type: object
required:
- icao
- identity
- live
- history
- links
- photos
properties:
icao:
type: string
identity:
type: object
properties:
registration:
type:
- string
- 'null'
icao_type:
type:
- string
- 'null'
description: ICAO type designator, e.g. A319.
type_description:
type:
- string
- 'null'
year:
type:
- integer
- 'null'
description: Year of manufacture, when the aircraft database has it.
db_flags:
type: integer
description: 'Bits: 0 military, 1 interesting, 2 PIA, 3 LADD.'
military:
type: boolean
interesting:
type: boolean
pia:
type: boolean
ladd:
type: boolean
trace_day:
type:
- string
- 'null'
format: date
description: The day whose track supplied type_description and year.
live:
type: object
required:
- seen_now
description: 'When seen_now is true, also: now, callsign, source (adsb_icao, mlat, tisb_icao…) and the aircraft.json fields lat, lon, alt_baro, alt_geom, gs, track, baro_rate, squawk, emergency, category, seen, seen_pos, mlat.'
properties:
seen_now:
type: boolean
now:
type: number
description: Time of the live data, Unix seconds.
callsign:
type:
- string
- 'null'
source:
type:
- string
- 'null'
description: Source of the current position.
additionalProperties: true
history:
type: object
properties:
first_day:
type:
- string
- 'null'
format: date
last_day:
type:
- string
- 'null'
format: date
days_last_30:
type: integer
description: Days with a track among today and the previous 29 (UTC).
total_days:
type: integer
archive_unavailable:
type: boolean
description: 'Present when the archive could not be listed: recent days only.'
links:
type: object
properties:
map:
type:
- string
- 'null'
format: uri
description: 'The public map on this aircraft: live, or its last track the map can show.'
history:
type: string
format: uri
photos:
type: object
properties:
page:
type:
- string
- 'null'
format: uri
description: Public photo page on Planespotters.net (no image in this API).
provider:
type: string
withheld:
type:
- string
- 'null'
enum:
- pia
- ladd
- null
description: Why there is no photo link.
headers:
X-FIA-Plan:
description: The key's plan (free, feeder, starter, pro, fleet, enterprise).
schema:
type: string
X-Since-Applied:
description: '1 when since was applied: only the points after it are in the trace. Absent: the file came whole.'
schema:
type: string
const: '1'
X-FIA-Used-Month:
description: Requests counted this month for the key.
schema:
type: integer
responses:
TooManyRequests:
description: Per-minute limit (key or, on Free, IP) or the plan's monthly quota. Per-minute answers carry Retry-After.
headers:
Retry-After:
description: Seconds to wait.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unavailable:
description: Live data is briefly unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Missing or invalid X-Api-Key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-Api-Key
description: 'Self-serve: https://flyitalyadsb.com/data/api/#api-key'
externalDocs:
description: 'API page: plans, endpoints, free key'
url: https://flyitalyadsb.com/data/api/