---
title: "ADS-B Exchange v2 compatibility"
description: "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."
url: https://flyitalyadsb.com/en/data/api/docs/adsbx-v2.md
page_for_people: https://flyitalyadsb.com/en/data/api/docs/adsbx-v2/
language: en
generated: 2026-11-01
license: CC BY-SA 4.0 (data)
---

# ADS-B Exchange v2 compatibility

> 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.

The same data answers in two formats, with the same key:

- **Our API**, `https://api.flyitalyadsb.com/v2`: our own conventions (radius in kilometres, `now` in seconds, one aircraft as an object). The rest of these docs describe it.
- **The ADS-B Exchange v2 format**, `https://api.flyitalyadsb.com/api/aircraft/v2`: the paths, key headers and JSON of the ADS-B Exchange v2 API, for code already written for it.

Plans, limits and counting are the same: a request counts once, whichever format it uses. New code can use either; the MCP server and the Apify Actor use our API.

## Switching

Change the host and put your FlyItalyADSB key in the header you already send:

| You call | Call instead |
|---|---|
| `https://adsbexchange.com/api/aircraft/v2/…` | `https://api.flyitalyadsb.com/api/aircraft/v2/…` |
| `https://gateway.adsbexchange.com/api/aircraft/v2/…` | `https://api.flyitalyadsb.com/api/aircraft/v2/…` |
| `https://adsbexchange-com1.p.rapidapi.com/v2/…` | `https://api.flyitalyadsb.com/api/aircraft/v2/…` |

The key is read from `api-auth` (ADS-B Exchange), `X-RapidAPI-Key` (RapidAPI) or `X-Api-Key`. `X-RapidAPI-Host` can stay; it is ignored. No key yet? [Get one free](https://flyitalyadsb.com/en/data/api/#api-key).

Before, on RapidAPI:

```sh
curl -H "X-RapidAPI-Key: RAPIDAPI_KEY" -H "X-RapidAPI-Host: adsbexchange-com1.p.rapidapi.com" \
  https://adsbexchange-com1.p.rapidapi.com/v2/lat/45.46/lon/9.19/dist/25/
```

After:

```sh
curl -H "X-RapidAPI-Key: YOUR_FLYITALYADSB_KEY" \
  https://api.flyitalyadsb.com/api/aircraft/v2/lat/45.46/lon/9.19/dist/25/
```

## Endpoints

| Endpoint | Returns |
|---|---|
| `/hex/{hex}` | aircraft by ICAO address; if not seen now, its last known position from the last 48 hours |
| `/icao/{hex}` | aircraft by ICAO address, only if seen now |
| `/callsign/{callsign}` | aircraft by callsign |
| `/registration/{reg}` | aircraft by registration |
| `/sqk/{squawk}` | aircraft squawking a code, e.g. `7700` |
| `/lat/{lat}/lon/{lon}/dist/{nm}` | aircraft within `nm` **nautical miles** of a point, each with `dst` (NM) and `dir` (degrees) from the point |
| `/point/{lat}/{lon}/{nm}` | the same, with the radius as the last segment |
| `/closest/{lat}/{lon}/{nm}` | the one aircraft closest to the point within `nm`, with `dst` and `dir` |
| `/mil` | military aircraft |

`hex`, `icao`, `callsign`, `registration` and `sqk` take up to 100 values separated by commas: `/hex/4ca7b4,3c6444`. A trailing slash is fine, as on ADS-B Exchange. Case does not matter. A value that cannot match anything (`/hex/zzz`) finds nothing: `200` with an empty list.

Also available here, in the same format: `/ladd`, `/pia`, `/type/{type}` and the aliases `/reg/` and `/squawk/`.

## The answer

A list answers in the format of readsb's `jv2` output, the one ADS-B Exchange serves, with the fields in the same order. A real answer for 25 NM around Milan, shortened to one aircraft and a few of its fields:

```json
{
  "ac": [
    {"hex": "34608f", "type": "adsb_icao", "flight": "IBE06CZ ", "r": "EC-NAZ", "t": "A20N",
     "alt_baro": 625, "gs": 154.0, "track": 349.0, "lat": 45.612255, "lon": 8.727882,
     "dst": 21.442, "dir": 295.4}
  ],
  "msg": "No error",
  "now": 1793120254002,
  "total": 17,
  "ctime": 1793120254002,
  "ptime": 32
}
```

- `now` and `ctime`: Unix time in **milliseconds**. `ptime`: how long the request took, in milliseconds.
- The aircraft are readsb's records, with the same fields as on ADS-B Exchange, unchanged; they are described in [Fields and units](https://flyitalyadsb.com/en/data/api/docs/fields.md). `dst` and `dir` are only in the radius queries, computed with readsb's own formulas, so they are the same numbers ADS-B Exchange gives.
- `/hex` with **one** value returns the aircraft object itself, as ADS-B Exchange does, with `now` (the time it was last seen) and `ctime`. Alongside it are `ac`, `msg`, `total` and `ptime`, so code that reads the list works too. A trailing comma (`/hex/4ca7b4,`) returns the list only.
- `/hex` also finds an aircraft we are not receiving now: its last position from the last 48 hours, with `seen` and `seen_pos` in seconds since then.
- Nothing found: status `200` with `"ac": []` and `"total": 0`.

## Limits and errors

The plans and limits are those of the rest of the API ([Limits and errors](https://flyitalyadsb.com/en/data/api/docs/limits-and-errors.md)). The radius is checked in kilometres. In nautical miles:

| Plan | Maximum radius |
|---|---|
| Free | 270 NM (500 km), above the 250 NM that ADS-B Exchange documents |
| Starter | 540 NM (1,000 km) |
| Pro, Business | no maximum |

Errors carry `msg`, as on ADS-B Exchange, followed by the same fields as in our API (`help`, `plans`, and `max_radius_nm` with `max_radius_km` when the radius is above the plan). The status codes are ours:

| Status | When |
|---|---|
| `400` | coordinates or radius are not valid numbers, or more than 100 values; not counted |
| `401` | missing or invalid key |
| `403` | radius above the plan |
| `404` | the path does not exist; not counted |
| `429` | per-minute limit or monthly quota; see `Retry-After` |

Plan and usage are in the `X-FIA-*` headers of every answer, as in our API.

## What is not available

- The routes of the ADS-B Exchange enterprise gateway: `/all`, `/minimal/…`, `/nohex/…`, `/airport/…`, `/geospatial/…`, `/operations/…`, `/traces/…`, and the `POST` versions of the lookups. For the track of an aircraft over a day, use [`/v2/history`](https://flyitalyadsb.com/en/data/api/docs/history.md).
- The aircraft are those our network receives. `/hex` looks back 48 hours like ADS-B Exchange, but only in our own tracks.

---

Written for AI assistants. The page for people is https://flyitalyadsb.com/en/data/api/docs/adsbx-v2/; 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.