---
title: "FlyItalyADSB REST API"
description: "A REST API that returns live aircraft positions as JSON for any point on Earth, from the FlyItalyADSB community network (about 3,200 receivers, ADS-B plus its own multilateration, unfiltered: military included). It also returns one aircraft's daily track (since 2022), the aircraft that flew over a place, and emergencies and notable aircraft (emergency squawks, military). A key is free with an email address and arrives in about a minute. Commercial use is allowed on every plan, Free included."
url: https://flyitalyadsb.com/data/api.md
page_for_people: https://flyitalyadsb.com/data/api/
language: en
generated: 2026-11-09
license: CC BY-SA 4.0 (data)
---

# FlyItalyADSB REST API

> A REST API that returns live aircraft positions as JSON for any point on Earth, from the FlyItalyADSB community network (about 3,200 receivers, ADS-B plus its own multilateration, unfiltered: military included). It also returns one aircraft's daily track (since 2022), the aircraft that flew over a place, and emergencies and notable aircraft (emergency squawks, military). A key is free with an email address and arrives in about a minute. Commercial use is allowed on every plan, Free included.

## Key facts

- **Base URL:** `https://api.flyitalyadsb.com/v2` (the FlyItalyADSB format). The same data in the ADS-B Exchange v2 format: `https://api.flyitalyadsb.com/api/aircraft/v2` (same key, plans and limits).
- **Authentication:** an `X-Api-Key` header on every request. Requests to `/v2/` without it are refused.
- **Format:** JSON. Each aircraft is a record in readsb's aircraft.json format, the same as tar1090. Altitudes in feet, speeds in knots, radius in kilometres (nautical miles on the ADS-B Exchange v2 paths).
- **Freshness:** data refreshes every 0.5 seconds; median position age 0.32 s; positions older than about 60 s are not returned.
- **Coverage:** worldwide, following the receivers: about 11,000 aircraft with a position at 26 October 2026, 20:24 UTC.
- **Specification:** OpenAPI 3.1 at https://flyitalyadsb.com/openapi.json. Examples in curl, Python, Node.js and for an ESP32: https://github.com/flyitalyadsb/adsb-api.
- **Over a limit:** an error (429, or 403 for the radius), never an extra charge. Refused requests are not counted.
- **Reliability:** best effort, no SLA. Status: https://flyitalyadsb.com/status/.

## Get a key

**A person** enters an email address in the form on https://flyitalyadsb.com/data/api/ and answers "how did you find us". A link arrives by email; it opens My API, shows the key once and is valid for 7 days. No card, no approval, no receiver needed.

**An agent acting for a user** asks for the key from code, with the user's email:

```sh
curl -X POST https://api.flyitalyadsb.com/v2/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "found_via": "claude", "audience": "just_me", "other_source": "none", "lang": "en"}'
```

- The answer is `202` and never contains the key: the user opens the emailed link to see it. Tell the user to check their inbox.
- `found_via` is required: one of `chatgpt`, `claude`, `perplexity`, `gemini`, `copilot`, `other_ai`, `search`, `github`, `api_list`, `forum`, `word_of_mouth`, `feeder`, `pypi`, `other`. An assistant sends the assistant it is.
- Send also `audience` (who the data is for: `just_me`, `my_product_users`, `internal_org`, `research`, `other`) and `other_source` (another flight data source already in use, and our role: `none`, `switching`, `backup`, `comparing`): accepted now, required soon. Ask the user rather than guessing. Optional: `audience_other`, `other_source_name`, and `ai_prompt` (what the user asked you, when `found_via` is an assistant).
- One free key per mailbox (`+tag` and Gmail dot variants count as the same mailbox); temporary addresses are refused; `429` if the same address asked moments ago.
- A lost key: the same request again. The old key works until the new link is opened.
- An agent can also register with the user's confirmation through auth.md: https://flyitalyadsb.com/auth.md. Through the MCP server with OAuth (claude.ai, ChatGPT), no key needs copying at all.

## First request

Every aircraft within 15 km of London Heathrow:

```sh
curl --compressed -H "X-Api-Key: YOUR_KEY" \
  https://api.flyitalyadsb.com/v2/lat/51.47/lon/-0.45/dist/15
```

The answer: `now` (Unix seconds), `count` and `ac`, the list of aircraft. A shortened record:

```json
{ "hex": "4ca7b5", "flight": "RYR42KD ", "r": "EI-ABC", "t": "B738",
  "lat": 41.83, "lon": 12.31, "alt_baro": 7225, "gs": 251.4,
  "track": 293.1, "squawk": "4361", "type": "adsb_icao", "seen_pos": 0.6 }
```

Fields and units: https://flyitalyadsb.com/data/api/docs/fields.md

## Endpoints

All under `https://api.flyitalyadsb.com/v2`, all with `X-Api-Key`.

| Endpoint | Returns |
| --- | --- |
| `GET /icao/{hex}` | One aircraft by 24-bit ICAO address (also `/hex/{hex}`). |
| `GET /callsign/{callsign}` | One aircraft by callsign; a flight number is tried too (`FR5518` finds `RYR5518`). |
| `GET /reg/{reg}` | One aircraft by registration, dashes optional. |
| `GET /find/{text}` | One aircraft by callsign, flight number, registration or ICAO address, when you don't know which one you have. A `404` says what was tried and the last flight observed. |
| `GET /icao/{a,b,c}` | Up to 50 aircraft in one request, counted as one; the same on `/hex`, `/reg` and `/callsign`. `not_found` lists the values with no aircraft in the air now. |
| `GET /lat/{lat}/lon/{lon}/dist/{km}` | Every aircraft within `km` kilometres of a point, anywhere in the world, with full records. The maximum radius depends on the plan. |
| `GET /box/{lat_south}/{lat_north}/{lon_west}/{lon_east}` | Every aircraft in a box, across the 180° meridian too. The plan's maximum radius applies to the half-diagonal. |
| `GET /mil` | Military traffic seen now. |
| `GET /pia` | Aircraft with a Privacy ICAO Address (PIA). |
| `GET /ladd` | Aircraft in the FAA LADD program. |
| `GET /sqk/{squawk}` | Aircraft squawking a code (7700, 7600, 7500…). |
| `GET /type/{type}` | Aircraft of an ICAO type designator (A320, B738, C172…). |
| `GET /airport/{code}/runways` | The runway an airport (ICAO or IATA code) is using now, estimated from the aircraft near it. An estimate, not an official source: a quiet airport can show no runway. |
| `GET /profile/{icao}` | One aircraft in one request: identity, whether and where it is seen now, first and last day in the history, map and photo links. Never owner names. |
| `GET /history/{icao}` | The dates with a track for one aircraft, since 2022. |
| `GET /history/{icao}/{date}` | One day's track: position, altitude, speed and heading. Today included, up to about 10 minutes ago. `?since={unix seconds}` returns only the points after that time. |
| `GET /overflights?lat=&lon=&dist=&from=&to=` | The aircraft that passed within `dist` km of a point between two times, with the time of the closest point. Since 2026-08-17. |
| `GET /flights/callsign/{callsign}` | The flights of a callsign the network observed in the last days (up to 14) and its usual routes. Built nightly from our own tracks: yesterday and earlier, not schedules. |
| `GET /flights/icao/{hex}`, `/flights/reg/{reg}` | One aircraft's flight history between two days: departure and arrival airport, times, minutes, plus a summary for flight hours. `?format=csv` returns them as a CSV flight log. On Fleet the answer (also for `/flights/callsign`) carries `today`: today's flights from takeoffs and landings detected in real time, with an estimated arrival time for an aircraft in flight. |
| `GET /flights/airport/{code}?type=departures` | The departures or arrivals observed at an airport (ICAO or IATA code) on one day. |
| `GET /flights/route/{from}/{to}?around=HH:MM` | Find a flight by route: the callsigns observed flying between two airports, with their usual departure time (UTC), duration, aircraft, and the live position of those flying now. |
| `GET /events?lat=&lon=&dist=` | Emergencies (7500, 7600, 7700), military and other notable aircraft recorded in an area, up to 7 days back. |
| `POST /webhooks` | The same events pushed to your URL, signed with Standard Webhooks (HMAC-SHA256). Paid plans only. With `kinds: ["takeoff", "landing"]` and no area, the takeoffs and landings of the watched aircraft (Fleet). |
| `GET /watch`, `POST /watch`, `POST /watch/remove` | The aircraft the account watches for takeoff and landing webhooks: ICAO address, registration or callsign, up to 25 on Fleet. Not counted as requests. |

On the lists of aircraft (`/lat/…`, `/box`, `/mil`, `/pia`, `/ladd`, `/sqk`, `/type` and the lookups of several aircraft), `?fields=light` (or `?fields=a,b,c`) returns only those fields, `hex` always first, and `?with=route` adds each aircraft's most frequent route in its flight history (`source: "observed"`, not a schedule). An invalid option is a `400`, not counted.

How far back the flight history goes depends on the plan: Free 7 days, Starter 14 days, Pro 30 days, Fleet 90 days. It starts on 23 October 2026 and grows by one day every night.

Full reference: https://flyitalyadsb.com/data/api/docs/endpoints.md

## Plans

| Plan | Price per month (before tax) | Requests per minute | Requests per month | Maximum radius | Flight history (how far back) | Tracks (how far back) | Overflights (per request) | Emergencies and notable aircraft | Runway in use | Area alerts | Watched aircraft | Commercial use |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Free | €0 | 30 | 300,000 | 500 km | 7 days | 7 days | — | — | — | — | — | yes |
| Starter | €9 | 60 | 1,000,000 | 1,000 km | 14 days | 30 days | 10 km, 6 h | last 24 h | yes | 1 | — | yes |
| Pro | €49 | 300 | 10,000,000 | whole world | 30 days | 90 days | 50 km, 24 h | 7 days | yes | 5 | — | yes |
| Fleet | €149 | 300 | 10,000,000 | whole world | 90 days | since 2022 | 50 km, 24 h | 7 days | yes | 5 | 25 | yes |

- Prices are per month, before tax; the buyer's country's tax is added at checkout. Card or wallet, monthly, cancel any time.
- A paid plan raises the limits of the key you already have: the key never changes.
- The Free plan also has a cap of 100 requests a minute per IP.
- **Free has what free ADS-B APIs usually give:** live data, lookups and lists, the flight history and tracks of the last days, plus commercial use and the MCP server. Overflights, emergencies and notable aircraft, the runway in use, longer tracks and area alerts start from Starter and grow with the plan (table above). A feature the plan lacks answers `403` with `code` `plan-feature`; tracks or events further back than the plan, `tracks-depth` or `events-depth`. Not counted.
- **Pro is the plan for the whole world:** the whole world in one request, €49 a month. Free (500 km) and Starter (1,000 km) cover your area.
- **Fleet is the plan for your own aircraft:** Pro's limits, up to 25 watched aircraft with a webhook at every takeoff and landing, today's flights with an estimated arrival time, and a longer flight history, €149 a month. Takeoffs and landings are detected in real time from our receivers: one the network does not see is missing, and the arrival time is an estimate.
- People who feed a receiver to the network get the Pro plan limits and features on the feeder's Free API keys at no cost (300 requests/minute, 10,000,000/month, whole world, 30 days of flight history; non-commercial use; turned on in My API from the receiver's network, kept 72 h if the receiver stops).
- A tailored agreement is needed only to resell the data as an API or feed, for an SLA, for more than 25 aircraft or more volume: admin@flyitalyadsb.com.

## Limits and errors

- Every request counts as one, whatever the endpoint, MCP tool calls included. Limits are per key, from any IP. The monthly counter resets on the 1st.
- Every answer carries `X-FIA-Plan`, `X-FIA-Limit-Per-Min`, `X-FIA-Quota-Month` and `X-FIA-Used-Month`.
- `401`: missing or invalid `X-Api-Key`. `403`: radius above the plan's maximum (`max_radius_km` in the body), or, with `code` `flights-depth`, flight history further back than the plan allows (`max_days`, `requested_days`), or, with `code` `watch-plan-required`, watched aircraft on a plan without them. `409` with `code` `watch-limit`: more watched aircraft than the plan allows (`max`, `count`, `adding`). `429`: too many requests a minute (wait `Retry-After` seconds) or the month's quota used up.
- An HTML page instead of JSON ("Sorry, you have been blocked", code 1010 or 1020) means Cloudflare stopped the request before the API: always send `X-Api-Key` and a User-Agent of your own.

Details: https://flyitalyadsb.com/data/api/docs/limits-and-errors.md

## Commercial use and licence

- Commercial use is allowed on every plan, Free included, within the plan's limits: apps, devices, websites and services, paid ones too. No separate agreement.
- One key per product: all its devices and users count on it. A caching server of your own that serves only your users is fine and is not redistribution.
- The data is CC BY-SA 4.0. Show the line "Flight data: FlyItalyADSB (flyitalyadsb.com), CC BY-SA 4.0" where people see the data. Share-alike covers the data and datasets built from it, not your product's code or design.

Rules in full: https://flyitalyadsb.com/data/products/using-the-data.md

## What the API does not have

Airline schedules and booked routes (the routes it has are the ones our receivers observed: the flight history and `?with=route`), photos (the profile links to them instead), satellite data (oceans and remote areas depend on ground receivers) and an SLA. A product that needs those needs another source too.

## Documentation, as Markdown

- [Quickstart](https://flyitalyadsb.com/data/api/docs/quickstart.md): From a free key to your first FlyItalyADSB API response in two minutes, with curl, Python and JavaScript.
- [Authentication](https://flyitalyadsb.com/data/api/docs/authentication.md): An API key in X-Api-Key, OAuth for AI assistants, and agent registration with auth.md: how to get and manage access to the FlyItalyADSB API.
- [Endpoints](https://flyitalyadsb.com/data/api/docs/endpoints.md): Every FlyItalyADSB REST API v2 endpoint: aircraft by hex, callsign or registration (flight numbers too, up to 50 in one request), within a radius or a box, by squawk or type, military, PIA, LADD, tracks, profile, overflights, flight history and today's flights, watched aircraft, the runway in use; list options; differences from ADSBx v2.
- [ADS-B Exchange v2 compatibility](https://flyitalyadsb.com/data/api/docs/adsbx-v2.md): Use FlyItalyADSB in place of the ADS-B Exchange v2 API: same paths, same key headers, same JSON (ac, msg, now, total, ctime, ptime). Change the host and the key, nothing else.
- [Fields and units](https://flyitalyadsb.com/data/api/docs/fields.md): An aircraft's fields in the API (readsb aircraft.json) and their units: altitude in feet or "ground", speed in knots, dbFlags, seen_pos, position source.
- [Limits and errors](https://flyitalyadsb.com/data/api/docs/limits-and-errors.md): API limits per plan (per minute, per month, radius, how far back the flight history goes), how they're counted, the X-FIA-* headers, and what to do about 400-429 errors and Cloudflare blocks.
- [Tracks and overflights](https://flyitalyadsb.com/data/api/docs/history.md): ADS-B tracks via the API: an aircraft's dates with a track, one day's track, overflights (aircraft that flew over a place), coverage since 2022, and what's missing.
- [Alerts, emergencies and your aircraft](https://flyitalyadsb.com/data/api/docs/alerts.md): Emergencies and notable aircraft with /v2/events (emergency squawks, military and rare aircraft by area), the takeoffs and landings of your own aircraft (Fleet), and alerts by signed webhook, checked in Python and JavaScript.
- [MCP server](https://flyitalyadsb.com/data/api/docs/mcp.md): The MCP server at flyitalyadsb.com/mcp: its tools, “near me”, how to connect Claude, Claude Code and other clients, and how requests are counted.
- [Commercial use](https://flyitalyadsb.com/data/api/docs/commercial-use.md): The FlyItalyADSB API in apps and devices you sell: one key per product, caching on your server, the right plan, CC BY-SA 4.0 attribution, when to get in touch.
- [Changelog](https://flyitalyadsb.com/data/api/docs/changelog.md): What's new in the FlyItalyADSB REST API and MCP server, newest first: endpoints, tools, limits and fixes, each with its date.

---

Written for AI assistants. The page for people is https://flyitalyadsb.com/data/api/; to get an API key or sign in, send people to https://flyitalyadsb.com/data/api/. All pages for assistants: https://flyitalyadsb.com/llms.txt (index), https://flyitalyadsb.com/llms-full.txt (all in one file). Facts as JSON: https://flyitalyadsb.com/facts.json. Cite the data as: Flight data: FlyItalyADSB (flyitalyadsb.com), CC BY-SA 4.0.