Tracce e sorvoli

Una traccia è il percorso di un aereo punto per punto, in un giorno: posizione, quota e velocità, con la stessa chiave e gli stessi limiti del resto dell’API. Per i voli, cioè aeroporto di partenza e di arrivo, orari e durata, vedi lo storico voli.

# le date con una traccia
curl -H "X-Api-Key: LA_TUA_CHIAVE" https://api.flyitalyadsb.com/v2/history/4ca7b5
# la traccia di un giorno
curl -H "X-Api-Key: LA_TUA_CHIAVE" https://api.flyitalyadsb.com/v2/history/4ca7b5/2026-09-15

Quanto indietro puoi leggere le tracce dipende dal piano: Free gli ultimi 7 giorni, Starter 30, Pro 90, Fleet tutto l’archivio dal 2022 (tabella dei limiti). Più indietro la risposta è 403 con code tracks-depth, e l’elenco delle date ha solo quelle che il piano può leggere.

• /history/{icao} risponde {"icao", "count", "dates": ["2026-08-17", …]}.
• /history/{icao}/{data} restituisce la traccia di quel giorno nel formato trace_full di readsb: icao, timestamp e trace, un elenco di punti. Ogni punto ha i secondi dopo timestamp, latitudine, longitudine, quota (piedi o "ground"), velocità e rotta, più altri campi descritti nella documentazione di readsb.
• L’header X-History-Source vale local (giorni recenti) o r2 (archivio); per oggi live (la traccia che readsb sta scrivendo, aggiornata mentre l’aereo vola) o store (un aereo che readsb non riceve più: solo posizione, quota e nominativo, gli altri campi sono null). Il primo accesso a un giorno d’archivio può essere un po’ più lento.
• ?since={secondi unix} restituisce solo i punti dopo quell’istante, anche per oggi: per seguire un aereo durante la giornata senza rileggere tutta la traccia (come).

Periodi coperti

Periodo	Contenuto
10/04/2022 – 04/10/2023	solo il primo e l’ultimo punto di ogni volo
25/07/2023 – 27/06/2024	traccia completa, con lacune (206 giorni)
dal 17/08/2026	traccia completa, ogni giorno

Dal 28/06/2024 al 16/08/2026 non ci sono tracce. Il dettaglio dei giorni mancanti è nell’archivio storico.

Cosa è passato sopra un luogo

/overflights elenca gli aerei la cui traccia è passata entro dist km da un punto tra from e to:

I sorvoli partono da Starter: fino a 10 km e 6 ore per richiesta con Starter, 50 km e 24 ore con Pro e Fleet. Con Free la risposta è 403 con code plan-feature.

curl -H "X-Api-Key: LA_TUA_CHIAVE" "https://api.flyitalyadsb.com/v2/overflights?lat=45.4642&lon=9.19&dist=3&from=2026-10-21T08:00:00Z&to=2026-10-21T10:00:00Z"

• Una voce per aereo, in ordine di closest_time. Ogni voce ha:
  • icao, r, t, dbFlags e i nominativi visti (callsigns);
  • closest_time e closest_km;
  • min_alt_ft: la quota minima nel cerchio, in piedi o "ground";
  • source: adsb, mlat, tisb o other;
  • positions: le posizioni ricevute dentro il cerchio. 0 vuol dire che il passaggio è la retta tra due posizioni appena fuori.
• from e to accettano ISO 8601 (UTC se manca il fuso) o secondi Unix. max_alt_ft tiene solo la parte bassa di ogni traccia, limit limita l’elenco (predefinito 100, massimo 500).
• Copertura: ogni giorno dal 17/08/2026, oggi compreso fino a circa 10 minuti fa. Per gli ultimi minuti e per quello che vola adesso usa /v2/lat/…. I periodi non cercati sono in coverage.gaps: lì “nessun aereo” non vuol dire che non è passato niente.
• Limiti: raggio e finestra dipendono dal piano: Starter 10 km e 6 ore, Pro e Fleet 50 km e 24 ore; il Free non comprende i sorvoli. Oltre, la risposta è 403. Ogni ricerca conta come una richiesta, e ogni chiave ne può fare al massimo 10 al minuto.
• Risposte troncate: se i passaggi sono più di quelli che stanno nella risposta, truncated vale true. complete_until dice fino a quando l’elenco è completo; per il resto, richiedi con from uguale a quell’istante.
• Riguarda gli aerei, non le persone: nessun campo dice chi c’era a bordo.

Cosa non c’è

• Nessuna ricerca per area su periodi lunghi: /overflights copre al massimo 24 ore e 50 km per richiesta, e solo dal 17/08/2026. Per estrazioni più ampie o progetti di ricerca scrivi a [email protected].
• Nessun dato grezzo: i messaggi Mode-S/ADS-B così come arrivano dai ricevitori non sono distribuiti, solo i dati decodificati.
• I dati sono CC BY-SA 4.0: cita FlyItalyADSB, e i lavori derivati vanno sotto la stessa licenza.