Turn an aircraft tail number, ICAO hex, or ADS-B Exchange link into a flight map, altitude and speed charts and reusable data.
Important
Status: historical traces are unavailable. ADS-B Exchange now limits historical data to browsers that pass a human-verification check, so --date, --start/--end and --url return "HTTP 403: Historical data requires a verified session." Recent traces, roughly the last 24 hours, still work. Historical support is paused while other data sources are evaluated; see the backlog.
pip install flight-tracer
flight-tracer trace --icao a40442No date means recent activity, roughly the last 24 hours. Historical dates are unavailable for now; see the status note above.
Example: An LAPD helicopter, N224LA, patrolling on an early Saturday morning. Rendered from a historical trace before ADS-B Exchange restricted access.
| You have | Command |
|---|---|
| ICAO hex | flight-tracer trace --icao a40442 |
| U.S. tail number | flight-tracer trace --n-number N358TV |
| Historical date (unavailable for now) | flight-tracer trace --icao a40442 --date 2026-09-16 |
| ADS-B Exchange link with a date (unavailable for now) | flight-tracer trace --url "https://globe.adsbexchange.com/?icao=a9a1ad&showTrace=2020-01-26" |
| Tail number to look up | flight-tracer resolve --n-number N358TV |
Tail-number lookup requires pip install "flight-tracer[faa]". A callsign such as FDX9756 cannot currently be used as an input; first find the aircraft's ICAO hex or tail number for that flight and date.
Most recipes below use historical dates, which currently return HTTP 403. The display options (--aspect-ratio, --background, --title, --label, presets and render) work the same on a recent trace: drop the date arguments to try them.
flight-tracer trace --n-number N868FD \
--start 2026-09-26 --end 2026-09-27 --leg allBoth dates are included. Each detected leg gets its own folder, plus an overview map. Use --leg 1 for one leg or --leg latest for the most recent detected leg.
flight-tracer trace --icao a9a1ad --date 2020-01-26 \
--after 2020-01-26T09:00:00 --before 2020-01-26T10:00:00 \
--window-timezone America/Los_Angeles --timezone America/Los_AngelesBounds are inclusive. Timestamps without an offset default to UTC unless --window-timezone is set. --timezone controls display separately. For older archives, --infer-legs can optionally detect explicit ground stops. See the detailed January 26 case study.
flight-tracer trace --icao a40442 --date 2026-09-16 \
--aspect-ratio 9:16 --timezone America/Los_AngelesPortrait outputs are 1080 × 1920. Local times appear alongside UTC; exported timestamps keep their full precision.
flight-tracer trace --icao a40442 --date 2026-09-16 \
--background osm --gap-minutes 2Connections across tracking gaps longer than two minutes are dashed. The default threshold is five minutes. The default basemap is esri-light; see all map styles, including Mapbox with your own token.
flight-tracer trace --icao a40442 --date 2026-09-16 \
--title "LAPD helicopter circles the San Fernando Valley" \
--label "34.2098,-118.4898,Van Nuys Airport" \
--label "34.2597,-118.4134,Whiteman Airport"--title and --dek replace the map's generated headline and time span. Each --label takes latitude, longitude and text, and the map widens to include it. On multi-leg runs, the title and dek go on the overview and labels go on every map. They're saved in annotations.json, so render reuses them.
flight-tracer render data/a40442_2026-09-16_2026-09-16 \
--background osm --aspect-ratio 9:16 --output variants/portraitRedraws images from the saved trace.csv without fetching the flight again. Data files are not rewritten. Saved annotations carry over; pass --title, --dek or --label to replace them.
# ~/.config/flight-tracer/presets.toml
[default]
timezone = "auto"
[social]
aspect-ratio = "9:16"
output = "~/Desktop/social"flight-tracer trace --icao a40442 --preset social
flight-tracer presets # show the file's location and contents[default] always applies. --preset NAME adds a named table on top, and flags override both. Keys are spelled like the flags. See the CLI reference for what presets can set.
flight-tracer trace --icao a40442 --date 2026-09-16 \
--no-plots --formats csv,geojson --output exportsA single-leg run writes:
data/a40442_2026-09-16_2026-09-16/
├── map.png # Route, start and last location, dates, attribution
├── altitude.png # Altitude over time
├── speed.png # Ground speed over time
├── trace.csv # Recorded points and decoded fields
├── points.geojson # Point geometries
├── line.geojson # Routes by leg
├── summary.json # Aircraft metadata, times and statistics
├── selection.json # Time bounds, leg selection and ground-filter settings
└── annotations.json # Custom title, dek and location labels, reused by render
For several detected legs, the root contains the full data and overview.png; subfolders such as leg1_FDX9756/ contain each leg's data and charts. Interactive runs ask which leg to use; --leg all skips the prompt. Non-interactive runs default to all legs.
Running the same aircraft/date selection again writes to the same folder. Use a different --output directory to keep variants.
Python 3.10 or newer is required. Optional extras add tail-number lookup and automatic timezone lookup:
pip install "flight-tracer[faa,tz]"
flight-tracer --version
flight-tracer trace --helpQuote extras such as [faa,tz] in zsh. To upgrade an existing installation:
pip install --upgrade flight-tracerFor local development, run this from the repository after installing dependencies:
pip install --no-deps -e .- Last location means last received position, not a confirmed landing or crash site.
- Check the data-quality notes. Each run reports tracking gaps, stale and multilaterated positions, missing metadata and how leg boundaries were found; the full set is in
summary.json. - Dashed segments approximate missing coverage. They do not establish the path flown. Exported route geometries include connections without dash styling.
- Legs use the archive's boundary flags. Older archives may lack them. Opt-in
--infer-legsuses explicit ground stops and labels its results as estimates; otherwise use a time window. Seven-field historical records are supported. - Date Line crossings are handled automatically. Maps wrap around the Pacific where appropriate; exported routes split at ±180°.
- Altitude and speed are raw, uncorrected values. Missing metadata stays empty. Times default to UTC; local time is opt-in.
| Guide | What you'll find |
|---|---|
| Recipes | Historical links, older archives, ground points, timezones and troubleshooting |
| Map styling | Aspect ratios, basemaps, Mapbox tokens, OSM caching and tracking gaps |
| Python examples | Fetching, selecting time windows, plotting and working with fleets |
| CLI reference | Options, defaults and date precedence |
| Changelog | Release history |
| Backlog | Prioritized feature ideas and maintenance work |
Run checks with python -m pytest tests/. tests/test_visual.py compares rendered maps and charts with the reference images in tests/baseline_images/. If a change to the output is intended, regenerate them with FLIGHT_TRACER_UPDATE_BASELINES=1 python -m pytest tests/test_visual.py and review the new images before committing. Pixels are only comparable within one matplotlib minor release, so regenerating records the version in tests/baseline_images/matplotlib-version.txt; other versions skip these tests, and a dedicated CI job runs them against the recorded version. Failed comparisons leave the new render and a diff in tests/visual_results/. See PUBLISH.md for the release workflow.
Flight data comes from ADS-B Exchange. Consider subscribing or contributing data. FAA tail-number resolution uses hangarbay. Keep the basemap attribution in exported maps.
FlightTracer is released under CC0 1.0. The bundled Inter typeface (flight_tracer/fonts/) is by The Inter Project Authors and keeps its own SIL Open Font License 1.1.
