Documentazione /

Compatibilità ADS-B Exchange v2

Usa FlyItalyADSB al posto dell'API v2 di ADS-B Exchange: stessi percorsi, stessi header della chiave, stesso JSON (ac, msg, now, total, ctime, ptime). Cambi host e chiave, nient'altro.

Aggiornato il 27 ottobre 2026

Gli stessi dati rispondono in due formati, con la stessa chiave:

La nostra API, https://api.flyitalyadsb.com/v2: le nostre convenzioni (raggio in chilometri, now in secondi, un aereo come oggetto). Il resto di questa documentazione descrive questa.
Il formato di ADS-B Exchange v2, https://api.flyitalyadsb.com/api/aircraft/v2: i percorsi, gli header della chiave e il JSON dell’API v2 di ADS-B Exchange, per il codice già scritto per quella.

Piani, limiti e conteggio sono gli stessi: una richiesta conta una volta, in qualunque formato. Per il codice nuovo vanno bene tutti e due; il server MCP e l’Actor Apify usano la nostra API.

Passare a FlyItalyADSB

Cambia l’host e metti la tua chiave FlyItalyADSB nell’header che mandi già:

Chiami	Chiama invece
`https://adsbexchange.com/api/aircraft/v2/…`	`https://api.flyitalyadsb.com/api/aircraft/v2/…`
`https://gateway.adsbexchange.com/api/aircraft/v2/…`	`https://api.flyitalyadsb.com/api/aircraft/v2/…`
`https://adsbexchange-com1.p.rapidapi.com/v2/…`	`https://api.flyitalyadsb.com/api/aircraft/v2/…`

La chiave si legge da api-auth (ADS-B Exchange), X-RapidAPI-Key (RapidAPI) o X-Api-Key. X-RapidAPI-Host può restare: viene ignorato. Non hai ancora una chiave? Prendila gratis.

Prima, su RapidAPI:

curl -H "X-RapidAPI-Key: CHIAVE_RAPIDAPI" -H "X-RapidAPI-Host: adsbexchange-com1.p.rapidapi.com" \
  https://adsbexchange-com1.p.rapidapi.com/v2/lat/45.46/lon/9.19/dist/25/

Dopo:

curl -H "X-RapidAPI-Key: LA_TUA_CHIAVE_FLYITALYADSB" \
  https://api.flyitalyadsb.com/api/aircraft/v2/lat/45.46/lon/9.19/dist/25/

Endpoint

Endpoint	Restituisce
`/hex/{hex}`	aerei per indirizzo ICAO; se ora non si vede, l’ultima posizione nota delle ultime 48 ore
`/icao/{hex}`	aerei per indirizzo ICAO, solo se si vedono adesso
`/callsign/{callsign}`	aerei per nominativo
`/registration/{reg}`	aerei per immatricolazione
`/sqk/{squawk}`	aerei con quel codice transponder, es. `7700`
`/lat/{lat}/lon/{lon}/dist/{nm}`	aerei entro `nm` miglia nautiche da un punto, ognuno con `dst` (NM) e `dir` (gradi) dal punto
`/point/{lat}/{lon}/{nm}`	lo stesso, con il raggio come ultimo segmento
`/closest/{lat}/{lon}/{nm}`	il solo aereo più vicino al punto entro `nm`, con `dst` e `dir`
`/mil`	aerei militari

hex, icao, callsign, registration e sqk accettano fino a 100 valori separati da virgole: /hex/4ca7b4,3c6444. La barra finale va bene, come su ADS-B Exchange. Maiuscole e minuscole sono uguali. Un valore che non può corrispondere a nulla (/hex/zzz) non trova nulla: 200 con la lista vuota.

Ci sono anche, nello stesso formato: /ladd, /pia, /type/{type} e gli alias /reg/ e /squawk/.

La risposta

Una lista risponde nel formato dell’output jv2 di readsb, quello che serve ADS-B Exchange, con i campi nello stesso ordine. Una risposta vera per 25 NM intorno a Milano, accorciata a un aereo e ad alcuni dei suoi campi:

{
  "ac": [
    {"hex": "34608f", "type": "adsb_icao", "flight": "IBE06CZ ", "r": "EC-NAZ", "t": "A20N",
     "alt_baro": 625, "gs": 154.0, "track": 349.0, "lat": 45.612255, "lon": 8.727882,
     "dst": 21.442, "dir": 295.4}
  ],
  "msg": "No error",
  "now": 1793120254002,
  "total": 17,
  "ctime": 1793120254002,
  "ptime": 32
}

now e ctime: ora Unix in millisecondi. ptime: quanto è durata la richiesta, in millisecondi.
Gli aerei sono i record di readsb, con gli stessi campi di ADS-B Exchange, senza modifiche; sono descritti in Campi e unità. dst e dir ci sono solo nelle ricerche per raggio, calcolati con le formule di readsb: sono gli stessi numeri di ADS-B Exchange.
/hex con un solo valore risponde con l’oggetto dell’aereo, come ADS-B Exchange, con now (l’ora in cui si è visto l’ultima volta) e ctime. Accanto ci sono ac, msg, total e ptime: funziona anche il codice che legge la lista. Una virgola in fondo (/hex/4ca7b4,) dà solo la lista.
/hex trova anche un aereo che ora non riceviamo: la sua ultima posizione delle ultime 48 ore, con seen e seen_pos in secondi da allora.
Nessun risultato: stato 200 con "ac": [] e "total": 0.

Limiti ed errori

Piani e limiti sono quelli del resto dell’API (Limiti ed errori). Il raggio si controlla in chilometri. In miglia nautiche:

Piano	Raggio massimo
Free	270 NM (500 km), più dei 250 NM che documenta ADS-B Exchange
Starter	540 NM (1.000 km)
Pro, Business	nessun massimo

Gli errori hanno msg, come su ADS-B Exchange, seguito dagli stessi campi della nostra API (help, plans, e max_radius_nm con max_radius_km quando il raggio supera il piano). I codici di stato sono i nostri:

Stato	Quando
`400`	coordinate o raggio non sono numeri validi, o più di 100 valori; non conta
`401`	chiave mancante o non valida
`403`	raggio sopra il piano
`404`	il percorso non esiste; non conta
`429`	limite al minuto o quota mensile; vedi `Retry-After`

Piano e consumo sono negli header X-FIA-* di ogni risposta, come nella nostra API.

Cosa non c’è

Le route del gateway enterprise di ADS-B Exchange: /all, /minimal/…, /nohex/…, /airport/…, /geospatial/…, /operations/…, /traces/…, e le versioni POST delle ricerche. Per la traccia di un aereo in un giorno usa /v2/history.
Gli aerei sono quelli che riceve la nostra rete. /hex guarda indietro 48 ore come ADS-B Exchange, ma solo nelle nostre tracce.