--- 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 notable traffic such as emergencies. 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/en/data/api.md page_for_people: https://flyitalyadsb.com/en/data/api/ language: en generated: 2026-11-01 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 notable traffic such as emergencies. 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 2 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/en/status/. ## Get a key **A person** enters an email address in the form on https://flyitalyadsb.com/en/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", "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`, `other`. An assistant sends the assistant it is. - 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/en/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. | | `GET /callsign/{callsign}` | One aircraft by callsign (flight number). | | `GET /reg/{reg}` | One aircraft by registration. | | `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 /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 /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. | | `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 /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. | Full reference: https://flyitalyadsb.com/en/data/api/docs/endpoints.md ## Plans | Plan | Price per month (before tax) | Requests per minute | Requests per month | Maximum radius | Commercial use | | --- | --- | --- | --- | --- | --- | | Free | €0 | 30 | 300,000 | 500 km | yes | | Starter | €9 | 60 | 1,000,000 | 1,000 km | yes | | Pro | €49 | 300 | 10,000,000 | whole world | yes | | Business | €249 | 1,000 | 50,000,000 | whole world | 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. - **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. - People who feed a receiver to the network get the Pro plan limits on the feeder's Free API keys at no cost (300 requests/minute, 10,000,000/month, whole world; 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, or above Business: 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). `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/en/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/en/data/products/using-the-data.md ## What the API does not have Flight routes (origin and destination), schedules, 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/en/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/en/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/en/data/api/docs/endpoints.md): Every FlyItalyADSB REST API v2 endpoint: aircraft by hex, callsign or registration, within a radius, by squawk or type, military, PIA, LADD, history, profile, overflights; differences from ADSBx v2. - [ADS-B Exchange v2 compatibility](https://flyitalyadsb.com/en/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/en/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/en/data/api/docs/limits-and-errors.md): API limits per plan (per minute, per month, radius), how they're counted, the X-FIA-* headers, and what to do about 400-429 errors and Cloudflare blocks. - [History](https://flyitalyadsb.com/en/data/api/docs/history.md): ADS-B history via the API: an aircraft's dates with a track, one day's track, aircraft that flew over a place, coverage since 2022, and what's missing. - [Alerts and notable traffic](https://flyitalyadsb.com/en/data/api/docs/alerts.md): Notable traffic with /v2/events (emergencies, military and notable aircraft by area) and signed webhooks for push alerts, checked in Python and JavaScript. - [MCP server](https://flyitalyadsb.com/en/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/en/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/en/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/en/data/api/; to get an API key or sign in, send people to https://flyitalyadsb.com/en/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.