Endpoint

Base URL: https://api.flyitalyadsb.com/v2. Tutti gli endpoint sono GET, rispondono in JSON e chiedono l’header X-Api-Key; le poche POST, per gestire webhook e aerei seguiti, sono in Avvisi. La specifica completa, leggibile da programmi, è in openapi.json. Il codice scritto per ADS-B Exchange v2 può usare invece il suo formato su https://api.flyitalyadsb.com/api/aircraft/v2.

Endpoint	Restituisce
/icao/{hex} (anche /hex/{hex})	un aereo per indirizzo ICAO a 24 bit
/callsign/{callsign}	un aereo per nominativo; prova anche il numero di volo (come)
/reg/{reg}	un aereo per immatricolazione, con o senza trattini
/find/{testo}	un aereo per nominativo, immatricolazione o indirizzo ICAO, quando non sai quale dei tre hai
/icao/{a,b,c} (anche /hex, /reg, /callsign)	fino a 50 aerei in una richiesta (come)
/lat/{lat}/lon/{lon}/dist/{km}	tutti gli aerei entro km chilometri da un punto
/box/{lat_sud}/{lat_nord}/{lon_ovest}/{lon_est}	tutti gli aerei in un riquadro (come)
/mil	il traffico militare visto ora
/pia	gli aerei con indirizzo ICAO privato (PIA)
/ladd	gli aerei del programma FAA LADD
/sqk/{squawk} (anche /squawk/{squawk})	gli aerei con quel codice transponder, per esempio 7700
/type/{type}	gli aerei di un tipo ICAO, per esempio A320
/airport/{code}/runways	la pista che un aeroporto usa adesso, stimata dagli aerei vicini (pista in uso)
/history/{icao}	le date con una traccia per un aereo
/history/{icao}/{data}	la traccia di un aereo in un giorno
/profile/{icao}	quello che sappiamo di un aereo: identità, stato live, riepilogo dello storico
/overflights?lat=&lon=&dist=&from=&to=	gli aerei passati entro dist km da un punto tra due istanti
/events?lat=…&lon=…&dist=…	le emergenze e gli aerei particolari (squawk di emergenza, militari) in un raggio, nelle ultime ore
/flights/callsign/{callsign}	i voli di un nominativo osservati dalla rete negli ultimi giorni, e le sue rotte abituali (storico voli)
/flights/icao/{hex}, /flights/reg/{reg}	lo storico voli di un aereo tra due giorni: partenza, arrivo, durata; con Fleet anche i voli di oggi
/flights/airport/{code}	le partenze o gli arrivi osservati in un aeroporto in un giorno
/flights/route/{from}/{to}	i nominativi osservati da un aeroporto a un altro, con l’orario di partenza abituale (trova il tuo volo)
/watch	gli aerei seguiti dal tuo account, per gli avvisi di decollo e atterraggio, con Fleet; si aggiungono e si tolgono con POST (i tuoi aerei)

Gli elenchi di aerei accettano delle opzioni: solo i campi che ti servono, la tratta di ogni aereo e altro.

Un aereo

/icao/{hex}, /callsign/{callsign} e /reg/{reg} restituiscono il record dell’aereo, se è visto in questo momento, altrimenti 404 con "error": "not found" e qualche campo che dice perché (qui sotto):

• l’hex è di 6 caratteri, maiuscole o minuscole, con o senza 0x; /hex/{hex} è lo stesso di /icao/{hex};
• nominativo e immatricolazione non distinguono maiuscole e minuscole, e gli spazi non contano; nell’immatricolazione non contano nemmeno trattini e punti.

Per seguire più aerei, chiedine fino a 50 in una richiesta.

curl -H "X-Api-Key: LA_TUA_CHIAVE" https://api.flyitalyadsb.com/v2/reg/I-ABCD

Nominativo e numero di volo

Il nominativo (callsign) è quello che l’aereo trasmette, per esempio BAW185 o RYR55NU. Spesso, non sempre, è il numero di volo scritto sul biglietto. /callsign accetta tutti e due e prova, in ordine:

• il nominativo com’è scritto;
• senza gli zeri dopo il prefisso della compagnia: CPA0289 trova CPA289;
• la forma ICAO del codice IATA della compagnia: FR5518 trova RYR5518, BA0185 trova BAW185, 5X1219 trova UPS1219.

Quando l’aereo è stato trovato con un’altra forma, la risposta ha due header, X-Matched-As: callsign e X-Matched-Value: RYR5518, leggibili anche da un browser. /reg confronta le immatricolazioni senza trattini, spazi e punti: SP-GPM, S-PGPM e SPGPM trovano lo stesso aereo.

Alcune compagnie usano di rado il numero di volo come nominativo. Ryanair, easyJet e Wizz Air volano quasi sempre con nominativi alfanumerici (RYR55NU), e nel segnale radio niente li collega al numero di volo. Per loro cerca per immatricolazione, oppure guarda la rotta nello storico voli.

/find/{testo} serve quando non sai cosa hai in mano: prova il testo come nominativo (con le forme qui sopra), come immatricolazione e come indirizzo ICAO, e dice come ha trovato ogni aereo, al massimo uno per tipo:

{
  "query": "FR5518",
  "count": 1,
  "results": [
    {"matched_as": "callsign", "value": "RYR5518",
     "aircraft": {"hex": "4d2247", "flight": "RYR5518 ", "r": "9H-QDF"}}
  ]
}

Queste ricerche rispondono solo per gli aerei in volo e visti dalla rete adesso. Altrimenti il 404 dice perché:

• tried: le forme provate (in /find, un elenco per tipo);
• hint: una breve spiegazione, per esempio che il numero di volo non è sempre il nominativo;
• found_as: quando il testo è un altro identificativo di un aereo in volo, per esempio un indirizzo ICAO mandato a /callsign, dove chiederlo: {"matched_as": "icao", "value": "4d2247", "path": "/v2/icao/4d2247"}. Non rispondiamo mai con un altro aereo al posto di quello che hai chiesto;
• last_seen: quando c’è, l’ultimo volo che la rete ha osservato negli ultimi 7 giorni, nel formato dello storico voli.

Gli aerei in un raggio

/lat/{lat}/lon/{lon}/dist/{km}, con coordinate in gradi decimali e raggio in chilometri, non miglia nautiche come in altre API ADS-B. Funziona ovunque nel mondo, anche a cavallo del meridiano 180°.

• Il raggio massimo dipende dal piano (vedi Limiti ed errori). Oltre, la risposta è 403 con max_radius_km.
• Pro e Fleet non hanno un massimo e possono chiedere tutto il mondo in una richiesta: /lat/0/lon/0/dist/20040.

La risposta è {"now", "count", "total", "ac": [...]}, gli stessi campi per ogni aereo (total è lo stesso numero di count).

Per un rettangolo invece di un cerchio usa /box. Per una risposta più leggera, o per la tratta di ogni aereo, vedi le opzioni delle liste.

Militari, PIA, LADD

/mil, /pia e /ladd restituiscono l’elenco di tutta la rete, nello stesso formato del raggio. Sono gli aerei con i bit corrispondenti di dbFlags (vedi Campi e unità). I dati non sono filtrati: gli aerei PIA e LADD sono segnalati, non nascosti.

Per squawk o tipo

/sqk/{squawk} (oppure /squawk/{squawk}) restituisce gli aerei con quel codice transponder: 4 cifre ottali, per esempio 7700, 7600, 7500. /type/{type} restituisce gli aerei di un designatore di tipo ICAO, maiuscole o minuscole, per esempio A320, B738, C172. Entrambi coprono tutta la rete, nello stesso formato del raggio. Un valore non valido risponde 400 e non viene contato.

curl -H "X-Api-Key: LA_TUA_CHIAVE" https://api.flyitalyadsb.com/v2/sqk/7700

Tracce e sorvoli

/history/{icao} elenca le date disponibili per un aereo, /history/{icao}/{YYYY-MM-DD} restituisce la traccia di quel giorno; con ?since= solo i punti dopo un istante. Periodi coperti e formato sono in Storico.

/overflights risponde a “cosa è passato sopra questo luogo tra questi due istanti”: una voce per aereo, con istante e distanza del punto più vicino. Parametri, copertura e limiti sono in Storico.

Storico voli

I voli che la rete ha osservato, costruiti ogni notte dalle sue tracce: aeroporto di partenza e di arrivo, orari e durata. Sono quello che i nostri ricevitori hanno visto, non gli orari delle compagnie: un’estremità che non si è vista è null.

Endpoint	Restituisce
/flights/callsign/{callsign}?days=7	i voli di un nominativo negli ultimi giorni (da 1 a 14, 7 se non lo indichi), dal più recente, e le sue rotte abituali in usual, con quante volte è stata volata ognuna
/flights/icao/{hex}?from=&to=	i voli di un aereo tra due giorni, YYYY-MM-DD (gli ultimi 7 se non li indichi, al massimo 31): il suo registro dei voli
/flights/reg/{reg}?from=&to=	lo stesso, per immatricolazione
/flights/airport/{code}?type=departures&date=	le partenze (departures, il default) o gli arrivi (arrivals) osservati in un aeroporto in un giorno; codice ICAO o IATA, l’ultimo giorno disponibile se non lo indichi
/flights/route/{from}/{to}?around=HH:MM	i nominativi osservati da un aeroporto all’altro, con l’orario di partenza abituale e, se volano adesso, dove sono (trova il tuo volo)

Un volo:

{
  "icao": "4d2247", "r": "9H-QDF", "t": "B738", "callsign": "RYR791K",
  "from": {"airport": "EGGD", "iata": "BRS", "name": "Bristol Airport", "country": "GB",
           "time": 1793882940, "seen": "ground"},
  "to":   {"airport": "EPKK", "iata": "KRK", "name": "Kraków John Paul II International Airport",
           "country": "PL", "time": 1793891880, "seen": "low"},
  "first_seen": 1793882940, "last_seen": 1793891880, "duration_min": 149, "day": "2026-11-05"
}

• from e to: l’aeroporto, time (secondi Unix), quando la rete ha visto l’aereo lì, e seen, come è stato riconosciuto l’aeroporto. Con ground e low l’orario è vicino al decollo o all’atterraggio; con approach può essere qualche minuto prima o dopo:
  • ground: a terra entro 6 km;
  • low: al massimo 2.500 piedi sopra l’aeroporto entro 15 km;
  • approach: al massimo 6.000 piedi entro 30 km, in direzione dell’aeroporto o in allontanamento.
• duration_min: i minuti dal primo all’ultimo punto osservato.
• day: il giorno UTC in cui è cominciato il volo. I voli a cavallo della mezzanotte UTC sono uniti.

La route per nominativo accetta le stesse forme di /callsign, quindi va bene anche il numero di volo. Le route per aereo restituiscono anche summary (voli, minuti, aeroporti), comodo per le ore di volo. Ogni risposta ha coverage, i giorni cercati. Un nominativo o un aereo senza voli nel periodo risponde 200 con count 0, e così un aeroporto senza voli visti quel giorno; un codice IATA che non conosciamo risponde 404.

I giorni si costruiscono dopo la mezzanotte UTC, verso le 02:45: ieri e i giorni prima ci sono, oggi non ancora. Su tutti i piani, una richiesta ciascuna; quanto indietro puoi chiedere dipende dal piano (qui sotto). Dove i ricevitori sono pochi, per esempio sugli oceani, può mancare un’estremità del volo.

Quanto indietro, per piano

Quanti giorni indietro da oggi (UTC) puoi chiedere:

Piano	Storico voli
Free	7 giorni
Starter	14 giorni
Pro	30 giorni
Fleet	90 giorni

Una chiave Free con il vantaggio feeder ha i 30 giorni del Pro.

Il limite vale sul giorno più vecchio che chiedi: from per un aereo, date per un aeroporto, days per un nominativo o una tratta. I limiti di ogni richiesta restano uguali su tutti i piani: fino a 14 giorni per un nominativo o una tratta, fino a 31 giorni per richiesta per un aereo (per un periodo più lungo, chiedilo a pezzi).

Se non indichi days, from o date, la finestra di default non va mai oltre la profondità del piano: subito dopo la mezzanotte UTC, prima che sia pronto il giorno della notte, è solo un giorno più corta. Se chiedi esplicitamente oltre la profondità del piano la risposta è 403, e non viene contata:

{
  "error": "flight history older than 7 days is not in this plan",
  "code": "flights-depth", "max_days": 7, "requested_days": 14,
  "docs": "https://flyitalyadsb.com/data/api/docs/endpoints/#observed-flights",
  "plans": "https://flyitalyadsb.com/data/api/?…#piani"
}

max_days è la profondità del piano, requested_days quanto indietro hai chiesto, plans il link ai piani.

Lo storico voli parte dal 23 ottobre 2026 e cresce di un giorno ogni notte: le profondità più lunghe si riempiono col passare dei giorni. coverage.missing elenca i giorni del tuo periodo che non ci sono.

I voli di oggi (Fleet)

I voli della notte si fermano a ieri. Con Fleet, /flights/icao/{hex}, /flights/reg/{reg} e /flights/callsign/{callsign} hanno anche today: i voli della giornata fin qui, costruiti dai decolli e dagli atterraggi che i nostri ricevitori rilevano in tempo reale, gli stessi che mandano gli avvisi di decollo e atterraggio. Per vederli qui non serve seguire l’aereo.

"today": {
  "available": true, "since": "2026-11-07", "source": "live", "count": 2,
  "flights": [
    {"icao": "4d2247", "callsign": "RYR5518",
     "from": {"airport": "EGSS", "time": "2026-11-07T08:58:20Z", "seen": "ground", "runway": "22", "place": "airport", "near": false},
     "to":   {"airport": "EIDW", "time": "2026-11-07T09:57:45Z", "seen": "low", "runway": "28L", "place": "airport", "near": false},
     "status": "landed", "duration_min": 59},
    {"icao": "4d2247", "callsign": "RYR5519",
     "from": {"airport": "EIDW", "time": "2026-11-07T10:41:05Z", "seen": "ground", "runway": "28L", "place": "airport", "near": false},
     "to": null, "status": "in_flight",
     "position": {"lat": 53.2, "lon": -4.95, "alt_ft": 24000, "gs_kt": 410.0, "track": 112.0},
     "eta": {"airport": "EGSS", "airport_iata": "STN", "time": "2026-11-07T11:19:30Z", "minutes": 30,
             "distance_km": 380, "estimate": true,
             "basis": "the usual destination of this callsign in the flight history, and distance / ground speed now"}}
  ],
  "note": "today's flights come from takeoffs and landings detected in real time from our receivers; …"
}

• since: il primo giorno UTC che non è ancora nei voli della notte: oggi, oppure ieri subito dopo la mezzanotte UTC, finché il giorno della notte non è pronto.
• from e to: l’aeroporto (il codice ICAO quando c’è), time (ISO 8601, UTC: non secondi Unix come nei voli della notte), seen (ground, low o approach, come sopra), runway quando si conosce, place (airport o heliport) e near, true quando l’aereo era a più di 2 km: di’ “vicino a” quell’aeroporto. from è null per un atterraggio senza un decollo visto da since.
• status: landed, con duration_min (dal decollo all’atterraggio); in_flight, con position (lat, lon, alt_ft, gs_kt, track) quando l’aereo vola adesso; unknown quando si è visto un decollo ma nessun atterraggio, e l’aereo adesso non vola (o è ridecollato senza un atterraggio visto).
• eta, solo per un aereo in volo e solo una stima: se la tratta abituale del nominativo nello storico voli parte dall’aeroporto del decollo di oggi, la sua destinazione, e il tempo che servirebbe in linea retta alla velocità al suolo di adesso. Niente eta senza una tratta abituale o sotto gli 80 nodi. Finché l’aereo sta ancora salendo la velocità è bassa e la stima viene in ritardo; non sa nulla della rotta, del vento o dell’avvicinamento. Non è mai un orario.
• I voli sono dal più vecchio. Decolli e atterraggi ripetuti, come i giri di campo, qui sono ognuno un volo.

È un rilevamento in tempo reale, quindi ha i limiti di quello che vedono i nostri ricevitori: un decollo o un atterraggio che la rete non vede manca (il volo resta unknown, o ha from null). Un atterraggio dedotto dalla scomparsa dell’aereo vicino a un campo compare circa 2,5 minuti dopo l’ultimo segnale, e sparisce di nuovo se l’aereo si rivede in volo entro 10 minuti. La notte dopo il giorno si ricostruisce dalle tracce complete nello storico voli.

Con gli altri piani today è {"available": false, "error": "…", "plans": "…"} e il resto della risposta non cambia. Queste risposte possono cambiare ogni minuto: restano in cache al massimo 15 secondi, privata (Cache-Control: private, max-age=15). ?format=csv ha solo i voli della notte. Sempre una richiesta.

Trova il tuo volo, per tratta

/flights/route/{from}/{to} serve quando conosci la tratta e più o meno l’orario, ma non il nominativo. Ryanair, easyJet e Wizz Air, per esempio, volano quasi sempre con nominativi che non sono il numero di volo. Elenca i nominativi che la rete ha visto volare da un aeroporto all’altro, dal più frequente:

curl -H "X-Api-Key: LA_TUA_CHIAVE" "https://api.flyitalyadsb.com/v2/flights/route/STN/DUB?around=09:30"

• from e to: codici ICAO o IATA.
• around=HH:MM, in UTC: solo i nominativi che partono di solito entro window minuti da quell’ora (90 se non lo indichi, da 15 a 720).
• days: quanti giorni indietro guardare, da 1 a 14, 7 se non lo indichi.

Un candidato:

{
  "callsign": "RYR5518", "flights": 3,
  "usual_departure_utc": "09:00", "usual_duration_min": 60, "last_day": "2026-11-05",
  "aircraft": [{"r": "9H-QDF", "t": "B738"}],
  "live": {"hex": "4d2247", "flight": "RYR5518 ", "lat": 52.0, "lon": -3.0, "alt_baro": 31000}
}

• flights: quante volte è stato osservato su questa tratta nel periodo.
• usual_departure_utc e usual_duration_min: l’orario di partenza (UTC) e la durata mediani di quei voli.
• last_day: l’ultimo giorno in cui è stato osservato su questa tratta.
• aircraft: fino a tre aerei che l’hanno volata più spesso, con immatricolazione (r, l’indirizzo ICAO se l’immatricolazione non si conosce) e tipo (t).
• live: solo se un aereo con quel nominativo vola adesso, il suo record live, lo stesso che restituisce /callsign.

La risposta ha anche from e to (codice, IATA, nome, paese), days, coverage, count e fino a 50 candidates. Una tratta senza voli nel periodo risponde 200 con count 0; un codice IATA che non conosciamo risponde 404. Sono i nominativi che i nostri ricevitori hanno visto sulla tratta, non gli orari delle compagnie: il nominativo è quello che l’aereo trasmette.

Registro dei voli in CSV

Aggiungi ?format=csv a /flights/icao/{hex} o /flights/reg/{reg} per avere gli stessi voli come file CSV (text/csv), una riga per volo, dal più vecchio, per un foglio di calcolo o un logbook:

day,callsign,icao,r,t,from,from_iata,from_time_utc,from_seen,to,to_iata,to_time_utc,to_seen,duration_min
2026-11-03,RYR5518,4d2247,9H-QDF,B738,EGSS,STN,2026-11-03 09:00:00,ground,EIDW,DUB,2026-11-03 10:00:00,low,60

Gli orari sono UTC. Un’estremità non osservata lascia vuote le sue colonne. Periodo, limiti e profondità sono quelli del JSON; una richiesta.

Pista in uso

/airport/{code}/runways stima la pista che un aeroporto sta usando adesso, dagli aerei che i nostri ricevitori vedono vicino. Il codice è ICAO o IATA:

La pista in uso parte da Starter; con Free la risposta è 403 con code plan-feature.

curl -H "X-Api-Key: LA_TUA_CHIAVE" https://api.flyitalyadsb.com/v2/airport/MXP/runways

{
  "airport": {"code": "LIMC", "iata": "MXP", "name": "Milan Malpensa International Airport", "country": "IT"},
  "now": 1794038400.5,
  "in_use": ["35R"],
  "runways": [{"runway": "35R", "heading": 350, "arrivals": 3, "departures": 1,
               "aircraft": [{"hex": "4d2247", "flight": "RYR5518", "kind": "arrival"}]}],
  "aircraft_nearby": 14,
  "known_runways": ["17L", "17R", "35L", "35R"],
  "note": "estimate from the aircraft our receivers see now near the airport; a quiet airport can show no runway"
}

• in_use: le piste con traffico adesso, dalla più trafficata. Vuoto se nessun aereo corrisponde.
• runways: per ognuna, heading (la direzione di marcia sulla pista, gradi veri), gli arrivi (arrivals) e le partenze (departures) contati adesso, e gli aerei (aircraft) che li fanno (kind: arrival o departure).
• aircraft_nearby: gli aerei con una posizione entro 25 km dall’aeroporto.
• known_runways: le piste aperte dell’aeroporto.

Un aereo conta per una pista quando è entro 25 km dall’aeroporto, a meno di 5.000 piedi sopra il campo, allineato con la pista (entro 20°) e al massimo a 1 km dal prolungamento del suo asse. Poi:

• arrivo: non in salita, fino a 18 km prima della soglia;
• partenza: in salita, sopra la pista o fino a 12 km dopo la sua fine;
• a terra: in corsa sulla pista ad almeno 40 nodi.

Con piste parallele vince l’asse più vicino.

È una stima di quello che succede adesso, non una fonte ufficiale. Un aeroporto tranquillo, o con pochi ricevitori intorno, può non mostrare nessuna pista: allora in_use è vuoto. Per pianificare un volo usa l’ATIS e le fonti ufficiali.

Le piste vengono da OurAirports (pubblico dominio), aggiornate ogni notte. Un aeroporto che non conosciamo risponde 404 (unknown airport code), e così un aeroporto senza dati sulle piste (no runway data for this airport). 503 con runway data is not available yet vuol dire che l’elenco delle piste non è ancora caricato: riprova più tardi. Una richiesta, su tutti i piani; la risposta si può tenere in cache per 15 secondi.

Opzioni delle liste

Opzioni per le risposte che sono elenchi di aerei, nel nostro formato /v2 (il formato ADS-B Exchange v2 non cambia). Si controllano per prime: un’opzione non valida risponde 400, con error e un link docs a questa sezione, e non viene contata.

Solo i campi che ti servono: fields

?fields=a,b,c tiene solo quei campi di ogni aereo. Vale su /lat/…/lon/…/dist/…, /box, /mil, /pia, /ladd, /sqk, /squawk, /type e sulle ricerche di più aerei.

curl -H "X-Api-Key: LA_TUA_CHIAVE" "https://api.flyitalyadsb.com/v2/lat/45.46/lon/9.19/dist/250?fields=light"

• hex c’è sempre, per primo.
• Un campo che l’aereo non ha manca, come nel record intero.
• fields=light è un insieme fisso per mappe e display: hex, flight, r, t, lat, lon, alt_baro, gs, track, squawk, seen_pos, category. Non cambia mai, quindi lo stesso URL dà sempre la stessa forma.
• Si possono mescolare preset e nomi: fields=light,rssi.
• Un nome sconosciuto risponde 400 con allowed, tutti i campi che puoi chiedere, e presets.
• La risposta mantiene la sua forma: {"now", "count", "total", "ac"}.

La tratta di ogni aereo: with=route

?with=route, sugli stessi elenchi, aggiunge a ogni aereo la tratta che il suo nominativo ha volato più spesso negli ultimi 7 giorni di storico voli:

"route": {"from": "EGSS", "from_iata": "STN", "to": "EIDW", "to_iata": "DUB",
          "count": 12, "last_day": "2026-11-05", "source": "observed"}

• from e to sono i codici ICAO degli aeroporti, count quante volte il nominativo ha volato la tratta in quei giorni, last_day l’ultima volta.
• È la stessa tratta della prima di usual in /flights/callsign/{callsign}.
• source: "observed": viene da quello che hanno visto i nostri ricevitori, non dagli orari delle compagnie. Un nominativo che vola tratte diverse oggi può essere su un’altra.
• Se nessuna tratta è nota, il campo route non c’è.
• with accetta solo route: un altro valore risponde 400. Si può combinare con fields.

Aerei in un riquadro: /box

/box/{lat_sud}/{lat_nord}/{lon_ovest}/{lon_est} restituisce tutti gli aerei in un rettangolo di latitudine e longitudine, nello stesso formato del raggio:

curl -H "X-Api-Key: LA_TUA_CHIAVE" https://api.flyitalyadsb.com/v2/box/44/46/8/10

• I bordi sono compresi. lat_sud deve essere minore di lat_nord, tutte e due tra -90 e 90; le longitudini sono tra -180 e 180.
• Un lon_ovest maggiore di lon_est attraversa il meridiano 180°: /box/50/60/170/-170 va da 170° E a 170° O.
• Il raggio massimo del piano vale sulla metà della diagonale, cioè la distanza dal centro del riquadro al suo punto più lontano (circa 137 km per /box/44/46/8/10). Così un riquadro non costa mai più di un cerchio che il piano permette. Oltre, la risposta è lo stesso 403 del raggio, con max_radius_km.
• Una richiesta, come il raggio.

Più aerei in una richiesta

/icao/, /hex/, /reg/ e /callsign/ accettano fino a 50 valori separati da virgole, e contano una richiesta:

curl -H "X-Api-Key: LA_TUA_CHIAVE" https://api.flyitalyadsb.com/v2/callsign/FR5518,CPA0289,EZY12AB

{
  "now": 1794038400.5, "count": 2, "total": 2, "ac": [{"hex": "4d2247", "flight": "RYR5518 "}, {"hex": "780a3c", "flight": "CPA289  "}],
  "not_found": ["EZY12AB"],
  "matched": {"FR5518": "RYR5518", "CPA0289": "CPA289"}
}

• Ogni valore accetta le stesse forme della ricerca singola: numeri di volo e zeri per i nominativi, trattini per le immatricolazioni, maiuscole e 0x per gli indirizzi ICAO.
• ac: gli aerei in volo adesso. Uno trovato da due valori compare una volta.
• not_found: i valori senza un aereo in volo adesso, come li hai scritti.
• matched: il valore che hai scritto e la forma trovata, solo quando sono diversi (l’header X-Matched-Value della ricerca singola).
• Basta una virgola, anche in fondo: /icao/4d2247,.
• Più di 50 valori, o nessuno, risponde 400 e non viene contato.
• Senza virgola la route risponde come sempre: l’aereo, oppure il 404 che spiega perché.

Solo i punti nuovi di una traccia: since

/history/{icao}/{data}?since={secondi unix} restituisce la traccia con i soli punti dopo quell’istante (il timestamp della traccia più lo scarto del punto maggiore di since), per oggi e per i giorni passati. Per seguire un aereo durante la giornata, chiedi con l’ora dell’ultimo punto che hai invece di rileggere tutto il giorno.

• Il resto del file non cambia, e la risposta ha l’header X-Since-Applied: 1. Senza quell’header il file è arrivato intero.
• since è in secondi, per esempio since=1794038400. Millisecondi, un valore negativo o qualcosa che non è un numero rispondono 400 e non vengono contati.
• Un since= vuoto è come nessun since.

Profilo di un aereo

/profile/{icao} mette insieme, in una richiesta, quello che gli altri endpoint dicono di un aereo:

• identity: immatricolazione, tipo ICAO (icao_type), type_description, year se il database degli aerei lo ha, e i bit di dbFlags già decodificati (military, interesting, pia, ladd);
• live: seen_now, e se lo riceviamo adesso nominativo, posizione, quota, velocità e source, la fonte della posizione (adsb_icao, mlat, tisb_icao…), con seen_pos in secondi;
• history: first_day e last_day con una traccia, days_last_30 (oggi e i 29 giorni prima, UTC) e total_days, dalle stesse date di /history/{icao};
• links: map, la mappa pubblica su questo aereo (live, o la sua ultima traccia che la mappa può mostrare), e history;
• photos: page, un link alle foto dell’aereo su Planespotters.net.

Risponde 404 se l’aereo non è ricevuto adesso e non ha storico.

curl -H "X-Api-Key: LA_TUA_CHIAVE" https://api.flyitalyadsb.com/v2/profile/3c66a3

Il profilo riguarda l’aereo: non restituisce mai i nomi di proprietari o operatori. Non contiene foto, perché le condizioni di Planespotters.net non permettono di servire le loro foto attraverso un’altra API: photos.page è un link alla loro pagina pubblica, dove ogni foto riporta il nome del fotografo, e il pannello dell’aereo sulla mappa ne mostra una allo stesso modo. Per gli aerei PIA e LADD photos.page è null e withheld dice perché. I loro dati restano nel profilo, segnalati, come in tutta l’API.

Emergenze, aerei particolari e avvisi

/events elenca le emergenze, i militari e gli altri aerei particolari che la rete ha registrato in una zona, e i piani a pagamento li possono ricevere come webhook firmati (POST /v2/webhooks). Tutto in Avvisi.

Se arrivi da ADSBx v2 o airplanes.live

Per tenere invariato il codice scritto per ADS-B Exchange v2 usa il formato ADS-B Exchange v2 su https://api.flyitalyadsb.com/api/aircraft/v2: stessi percorsi, header della chiave e JSON, cambiano solo host e chiave. L’elenco qui sotto riguarda la nostra /v2.

I record degli aerei hanno gli stessi campi (quelli di readsb) e i nomi delle route sono gli stessi per /callsign, /icao, /reg, /lat/…/lon/…/dist/…, /mil, /pia, /ladd, /sqk, /squawk e /type. Cosa cambia:

• Chiave: qui sempre l’header X-Api-Key; ADSBx usa l’header del suo fornitore.
• Raggio in /lat/…/lon/…/dist/…: qui chilometri, là miglia nautiche.
• /icao, /callsign, /reg: qui l’oggetto dell’aereo (404 se non lo vediamo), là un elenco {"ac": [...]}.
• now: qui secondi Unix, là millisecondi.
• Numero di aerei: qui count e total, là total.
• /hex: qui è un alias di /icao.
• Non disponibili in /v2: /registration, /point, /closest. Usa /reg e /lat/…/lon/…/dist/…, oppure il formato ADS-B Exchange v2, che ha /registration, /point e /closest.

Errori

Gli errori sono JSON con un campo error in chiaro. Codici e rimedi sono in Limiti ed errori.