{ "openapi": "3.1.0", "info": { "title": "FlyItalyADSB API", "version": "2", "summary": "Live and historical aircraft positions worldwide from the FlyItalyADSB community ADS-B/MLAT network. Commercial use allowed on every plan, Free included; the whole world in one request from the Pro plan (€49/month).", "description": "Unfiltered aircraft data (no FAA/LADD/BARR filtering; military aircraft included, many of them via MLAT) from a global community-run receiver network (about 3,200 receivers, densest in North America and Europe; any point on Earth can be queried), as readsb aircraft.json records (the same format as tar1090), plus an ADS-B Exchange v2–compatible variant at /api/aircraft/v2. Every endpoint except the key signup needs an X-Api-Key; keys are self-serve (see /auth.md). Plans and limits: https://flyitalyadsb.com/en/data/api/#piani. The same key works on the MCP server at https://flyitalyadsb.com/mcp. The same data is also served in the ADS-B Exchange v2 format (same paths, key headers and JSON; radius in nautical miles) at https://api.flyitalyadsb.com/api/aircraft/v2, documented at https://flyitalyadsb.com/en/data/api/docs/adsbx-v2/.", "termsOfService": "https://flyitalyadsb.com/en/terms/", "contact": { "name": "FlyItalyADSB", "email": "info@flyitalyadsb.com", "url": "https://flyitalyadsb.com/en/contact/" }, "license": { "name": "Data: CC BY-SA 4.0", "url": "https://creativecommons.org/licenses/by-sa/4.0/" } }, "externalDocs": { "description": "API page: plans, endpoints, free key", "url": "https://flyitalyadsb.com/en/data/api/" }, "servers": [ { "url": "https://api.flyitalyadsb.com" } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "live", "description": "What the network is receiving now." }, { "name": "history", "description": "Tracks: per-aircraft daily tracks since 2022-04-10, with gaps, and the aircraft that flew over a place (since 2026-08-17)." }, { "name": "flights", "description": "Flight history: the flights the network saw (departure and arrival airport, times, duration), built every night from its own tracks since 2026-10-23; yesterday and earlier; not airline schedules. How far back depends on the plan. On Fleet the aircraft and callsign answers also carry today's flights, from takeoffs and landings detected in real time. https://flyitalyadsb.com/en/data/api/docs/endpoints/#observed-flights" }, { "name": "keys", "description": "Self-serve API keys." }, { "name": "account", "description": "The key's account: the position saved for \"aircraft near me\"." }, { "name": "events", "description": "Emergencies and notable aircraft recorded by the network: emergency squawks, military, \"interesting\". https://flyitalyadsb.com/en/data/api/docs/alerts/" }, { "name": "webhooks", "description": "Signed push alerts on the same events, paid plans only; on Fleet also the takeoffs and landings of the watched aircraft. https://flyitalyadsb.com/en/data/api/docs/alerts/" }, { "name": "watch", "description": "The aircraft the account watches for takeoff and landing webhooks (Fleet 25). Not counted as requests. https://flyitalyadsb.com/en/data/api/docs/alerts/#aircraft" } ], "paths": { "/v2/icao/{hex}": { "get": { "summary": "One aircraft by ICAO address", "description": "Up to 50 comma-separated values (one comma is enough, at the end too) return a list instead, counted as ONE request: `{now, count, total, ac, not_found, matched}`, each value with the same tolerant forms; then `fields` and `with` apply. Without a comma, the single aircraft or the explained 404. https://flyitalyadsb.com/en/data/api/docs/endpoints/#several-aircraft-in-one-request", "tags": [ "live" ], "parameters": [ { "name": "hex", "in": "path", "required": true, "description": "24-bit ICAO address, hex (case-insensitive, an 0x prefix is accepted). Or up to 50 of them, comma-separated.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "required": false, "description": "Only these fields of each aircraft, comma-separated. `light` = hex, flight, r, t, lat, lon, alt_baro, gs, track, squawk, seen_pos, category (a fixed list). Presets and names can be mixed (`light,rssi`). `hex` is always present and first; a field the aircraft does not have is missing, as in the full record. An unknown name: 400 with `allowed` and `presets`, not counted. https://flyitalyadsb.com/en/data/api/docs/endpoints/#list-options", "schema": { "type": "string", "examples": [ "light", "hex,flight,lat,lon,alt_baro", "light,rssi" ] } }, { "name": "with", "in": "query", "required": false, "description": "`route` adds `route` to each aircraft whose callsign has a known route: the most frequent one in the latest 7 days of observed flights (not a schedule). The field is absent when no route is known. Any other value: 400, not counted.", "schema": { "type": "string", "enum": [ "route" ] } } ], "responses": { "200": { "description": "One value: the aircraft currently seen with this identifier, unchanged; X-Matched-As and X-Matched-Value are present when it was found under another form of the identifier. Comma-separated values: the aircraft in the air now, with `not_found` and `matched`.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" }, "X-Matched-As": { "$ref": "#/components/headers/X-Matched-As" }, "X-Matched-Value": { "$ref": "#/components/headers/X-Matched-Value" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Aircraft" }, { "$ref": "#/components/schemas/MultiAircraftList" } ] } } } }, "400": { "description": "More than 50 comma-separated values, or none, or an invalid list option; not counted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No aircraft with this identifier is in the air and seen by the network right now. The body says what was tried, a hint, `found_as` when the text is another identifier of an airborne aircraft, and `last_seen`, the last observed flight, when there is one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupNotFound" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v2/hex/{hex}": { "get": { "summary": "One aircraft by ICAO address (alias of /v2/icao)", "description": "Up to 50 comma-separated values (one comma is enough, at the end too) return a list instead, counted as ONE request: `{now, count, total, ac, not_found, matched}`, each value with the same tolerant forms; then `fields` and `with` apply. Without a comma, the single aircraft or the explained 404. https://flyitalyadsb.com/en/data/api/docs/endpoints/#several-aircraft-in-one-request", "tags": [ "live" ], "parameters": [ { "name": "hex", "in": "path", "required": true, "description": "24-bit ICAO address, hex (case-insensitive, an 0x prefix is accepted). Or up to 50 of them, comma-separated.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "required": false, "description": "Only these fields of each aircraft, comma-separated. `light` = hex, flight, r, t, lat, lon, alt_baro, gs, track, squawk, seen_pos, category (a fixed list). Presets and names can be mixed (`light,rssi`). `hex` is always present and first; a field the aircraft does not have is missing, as in the full record. An unknown name: 400 with `allowed` and `presets`, not counted. https://flyitalyadsb.com/en/data/api/docs/endpoints/#list-options", "schema": { "type": "string", "examples": [ "light", "hex,flight,lat,lon,alt_baro", "light,rssi" ] } }, { "name": "with", "in": "query", "required": false, "description": "`route` adds `route` to each aircraft whose callsign has a known route: the most frequent one in the latest 7 days of observed flights (not a schedule). The field is absent when no route is known. Any other value: 400, not counted.", "schema": { "type": "string", "enum": [ "route" ] } } ], "responses": { "200": { "description": "One value: the aircraft currently seen with this identifier, unchanged; X-Matched-As and X-Matched-Value are present when it was found under another form of the identifier. Comma-separated values: the aircraft in the air now, with `not_found` and `matched`.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" }, "X-Matched-As": { "$ref": "#/components/headers/X-Matched-As" }, "X-Matched-Value": { "$ref": "#/components/headers/X-Matched-Value" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Aircraft" }, { "$ref": "#/components/schemas/MultiAircraftList" } ] } } } }, "400": { "description": "More than 50 comma-separated values, or none, or an invalid list option; not counted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No aircraft with this identifier is in the air and seen by the network right now. The body says what was tried, a hint, `found_as` when the text is another identifier of an airborne aircraft, and `last_seen`, the last observed flight, when there is one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupNotFound" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v2/callsign/{callsign}": { "get": { "summary": "One aircraft by callsign (flight numbers tried too)", "description": "Tries, in order: the callsign as written; without the zeros after the airline prefix (CPA0289 -> CPA289); the ICAO form of the airline's IATA code (FR5518 -> RYR5518, 5X1219 -> UPS1219). Some airlines (Ryanair, easyJet, Wizz Air) mostly fly alphanumeric callsigns not linked to the flight number. https://flyitalyadsb.com/en/data/api/docs/endpoints/#callsign-and-flight-number Up to 50 comma-separated values (one comma is enough, at the end too) return a list instead, counted as ONE request: `{now, count, total, ac, not_found, matched}`, each value with the same tolerant forms; then `fields` and `with` apply. Without a comma, the single aircraft or the explained 404. https://flyitalyadsb.com/en/data/api/docs/endpoints/#several-aircraft-in-one-request", "tags": [ "live" ], "parameters": [ { "name": "callsign", "in": "path", "required": true, "description": "Callsign as transmitted (e.g. RYR55NU, BAW185) or a flight number (e.g. FR5518, BA0185); case and spaces ignored. Or up to 50 of them, comma-separated.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "required": false, "description": "Only these fields of each aircraft, comma-separated. `light` = hex, flight, r, t, lat, lon, alt_baro, gs, track, squawk, seen_pos, category (a fixed list). Presets and names can be mixed (`light,rssi`). `hex` is always present and first; a field the aircraft does not have is missing, as in the full record. An unknown name: 400 with `allowed` and `presets`, not counted. https://flyitalyadsb.com/en/data/api/docs/endpoints/#list-options", "schema": { "type": "string", "examples": [ "light", "hex,flight,lat,lon,alt_baro", "light,rssi" ] } }, { "name": "with", "in": "query", "required": false, "description": "`route` adds `route` to each aircraft whose callsign has a known route: the most frequent one in the latest 7 days of observed flights (not a schedule). The field is absent when no route is known. Any other value: 400, not counted.", "schema": { "type": "string", "enum": [ "route" ] } } ], "responses": { "200": { "description": "One value: the aircraft currently seen with this identifier, unchanged; X-Matched-As and X-Matched-Value are present when it was found under another form of the identifier. Comma-separated values: the aircraft in the air now, with `not_found` and `matched`.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" }, "X-Matched-As": { "$ref": "#/components/headers/X-Matched-As" }, "X-Matched-Value": { "$ref": "#/components/headers/X-Matched-Value" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Aircraft" }, { "$ref": "#/components/schemas/MultiAircraftList" } ] } } } }, "400": { "description": "More than 50 comma-separated values, or none, or an invalid list option; not counted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No aircraft with this identifier is in the air and seen by the network right now. The body says what was tried, a hint, `found_as` when the text is another identifier of an airborne aircraft, and `last_seen`, the last observed flight, when there is one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupNotFound" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v2/reg/{reg}": { "get": { "summary": "One aircraft by registration", "description": "Up to 50 comma-separated values (one comma is enough, at the end too) return a list instead, counted as ONE request: `{now, count, total, ac, not_found, matched}`, each value with the same tolerant forms; then `fields` and `with` apply. Without a comma, the single aircraft or the explained 404. https://flyitalyadsb.com/en/data/api/docs/endpoints/#several-aircraft-in-one-request", "tags": [ "live" ], "parameters": [ { "name": "reg", "in": "path", "required": true, "description": "Registration, e.g. MM62179; case, spaces, dashes and dots ignored (SP-GPM = SPGPM). Or up to 50 of them, comma-separated.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "required": false, "description": "Only these fields of each aircraft, comma-separated. `light` = hex, flight, r, t, lat, lon, alt_baro, gs, track, squawk, seen_pos, category (a fixed list). Presets and names can be mixed (`light,rssi`). `hex` is always present and first; a field the aircraft does not have is missing, as in the full record. An unknown name: 400 with `allowed` and `presets`, not counted. https://flyitalyadsb.com/en/data/api/docs/endpoints/#list-options", "schema": { "type": "string", "examples": [ "light", "hex,flight,lat,lon,alt_baro", "light,rssi" ] } }, { "name": "with", "in": "query", "required": false, "description": "`route` adds `route` to each aircraft whose callsign has a known route: the most frequent one in the latest 7 days of observed flights (not a schedule). The field is absent when no route is known. Any other value: 400, not counted.", "schema": { "type": "string", "enum": [ "route" ] } } ], "responses": { "200": { "description": "One value: the aircraft currently seen with this identifier, unchanged; X-Matched-As and X-Matched-Value are present when it was found under another form of the identifier. Comma-separated values: the aircraft in the air now, with `not_found` and `matched`.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" }, "X-Matched-As": { "$ref": "#/components/headers/X-Matched-As" }, "X-Matched-Value": { "$ref": "#/components/headers/X-Matched-Value" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Aircraft" }, { "$ref": "#/components/schemas/MultiAircraftList" } ] } } } }, "400": { "description": "More than 50 comma-separated values, or none, or an invalid list option; not counted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No aircraft with this identifier is in the air and seen by the network right now. The body says what was tried, a hint, `found_as` when the text is another identifier of an airborne aircraft, and `last_seen`, the last observed flight, when there is one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupNotFound" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v2/find/{text}": { "get": { "summary": "One aircraft by callsign, flight number, registration or ICAO address", "description": "For when you do not know which identifier you have: tries the text as a callsign (with the same forms as /v2/callsign), a registration (dashes ignored) and an ICAO address, and says how each airborne aircraft matched (at most one per kind, the same aircraft once). https://flyitalyadsb.com/en/data/api/docs/endpoints/#callsign-and-flight-number", "tags": [ "live" ], "parameters": [ { "name": "text", "in": "path", "required": true, "description": "A callsign, flight number, registration or ICAO address.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The airborne aircraft that match.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No aircraft with this identifier is in the air and seen by the network right now. The body says what was tried, a hint, `found_as` when the text is another identifier of an airborne aircraft, and `last_seen`, the last observed flight, when there is one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupNotFound" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v2/lat/{lat}/lon/{lon}/dist/{dist}": { "get": { "summary": "All aircraft within a radius of a point", "description": "The radius is in kilometres (ADSBx v2 uses nautical miles). The maximum radius depends on the plan: https://flyitalyadsb.com/en/data/api/#piani.", "tags": [ "live" ], "parameters": [ { "name": "lat", "in": "path", "required": true, "description": "Latitude, decimal degrees.", "schema": { "type": "number" } }, { "name": "lon", "in": "path", "required": true, "description": "Longitude, decimal degrees.", "schema": { "type": "number" } }, { "name": "dist", "in": "path", "required": true, "description": "Radius in km.", "schema": { "type": "number", "minimum": 0 } }, { "name": "fields", "in": "query", "required": false, "description": "Only these fields of each aircraft, comma-separated. `light` = hex, flight, r, t, lat, lon, alt_baro, gs, track, squawk, seen_pos, category (a fixed list). Presets and names can be mixed (`light,rssi`). `hex` is always present and first; a field the aircraft does not have is missing, as in the full record. An unknown name: 400 with `allowed` and `presets`, not counted. https://flyitalyadsb.com/en/data/api/docs/endpoints/#list-options", "schema": { "type": "string", "examples": [ "light", "hex,flight,lat,lon,alt_baro", "light,rssi" ] } }, { "name": "with", "in": "query", "required": false, "description": "`route` adds `route` to each aircraft whose callsign has a known route: the most frequent one in the latest 7 days of observed flights (not a schedule). The field is absent when no route is known. Any other value: 400, not counted.", "schema": { "type": "string", "enum": [ "route" ] } } ], "responses": { "200": { "description": "Aircraft within the radius.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AircraftList" } } } }, "400": { "description": "lat, lon or dist is not a number, or an invalid list option.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The radius is above the plan's maximum (the body carries max_radius_km and a link to the plans).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v2/box/{lat_south}/{lat_north}/{lon_west}/{lon_east}": { "get": { "summary": "All aircraft in a latitude/longitude box", "description": "Edges included. lon_west greater than lon_east crosses the antimeridian (170/-170 = from 170 E to 170 W). The plan's maximum radius applies to the half-diagonal, the great-circle distance from the centre of the box to its farthest point; above it, the same 403 as the radius. One request. https://flyitalyadsb.com/en/data/api/docs/endpoints/#aircraft-in-a-box", "tags": [ "live" ], "parameters": [ { "name": "lat_south", "in": "path", "required": true, "description": "Southern edge, decimal degrees, below lat_north.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lat_north", "in": "path", "required": true, "description": "Northern edge, decimal degrees.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon_west", "in": "path", "required": true, "description": "Western edge, decimal degrees.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "lon_east", "in": "path", "required": true, "description": "Eastern edge, decimal degrees; different from lon_west.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "fields", "in": "query", "required": false, "description": "Only these fields of each aircraft, comma-separated. `light` = hex, flight, r, t, lat, lon, alt_baro, gs, track, squawk, seen_pos, category (a fixed list). Presets and names can be mixed (`light,rssi`). `hex` is always present and first; a field the aircraft does not have is missing, as in the full record. An unknown name: 400 with `allowed` and `presets`, not counted. https://flyitalyadsb.com/en/data/api/docs/endpoints/#list-options", "schema": { "type": "string", "examples": [ "light", "hex,flight,lat,lon,alt_baro", "light,rssi" ] } }, { "name": "with", "in": "query", "required": false, "description": "`route` adds `route` to each aircraft whose callsign has a known route: the most frequent one in the latest 7 days of observed flights (not a schedule). The field is absent when no route is known. Any other value: 400, not counted.", "schema": { "type": "string", "enum": [ "route" ] } } ], "responses": { "200": { "description": "Aircraft in the box.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AircraftList" } } } }, "400": { "description": "An edge is not a number or out of range, lat_south is not below lat_north, lon_west equals lon_east, or an invalid list option; not counted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The half-diagonal is above the plan's maximum radius (the body carries max_radius_km and a link to the plans).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v2/mil": { "get": { "summary": "Military aircraft", "description": "Aircraft whose dbFlags has the military bit (bit 0).", "tags": [ "live" ], "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Only these fields of each aircraft, comma-separated. `light` = hex, flight, r, t, lat, lon, alt_baro, gs, track, squawk, seen_pos, category (a fixed list). Presets and names can be mixed (`light,rssi`). `hex` is always present and first; a field the aircraft does not have is missing, as in the full record. An unknown name: 400 with `allowed` and `presets`, not counted. https://flyitalyadsb.com/en/data/api/docs/endpoints/#list-options", "schema": { "type": "string", "examples": [ "light", "hex,flight,lat,lon,alt_baro", "light,rssi" ] } }, { "name": "with", "in": "query", "required": false, "description": "`route` adds `route` to each aircraft whose callsign has a known route: the most frequent one in the latest 7 days of observed flights (not a schedule). The field is absent when no route is known. Any other value: 400, not counted.", "schema": { "type": "string", "enum": [ "route" ] } } ], "responses": { "200": { "description": "Matching aircraft.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AircraftList" } } } }, "400": { "description": "An invalid list option, not counted: an unknown name in `fields` (the body carries `allowed` and `presets`) or a `with` other than `route`. The body links the docs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v2/pia": { "get": { "summary": "PIA aircraft", "description": "Aircraft whose dbFlags has the PIA (Privacy ICAO Address) bit (bit 2).", "tags": [ "live" ], "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Only these fields of each aircraft, comma-separated. `light` = hex, flight, r, t, lat, lon, alt_baro, gs, track, squawk, seen_pos, category (a fixed list). Presets and names can be mixed (`light,rssi`). `hex` is always present and first; a field the aircraft does not have is missing, as in the full record. An unknown name: 400 with `allowed` and `presets`, not counted. https://flyitalyadsb.com/en/data/api/docs/endpoints/#list-options", "schema": { "type": "string", "examples": [ "light", "hex,flight,lat,lon,alt_baro", "light,rssi" ] } }, { "name": "with", "in": "query", "required": false, "description": "`route` adds `route` to each aircraft whose callsign has a known route: the most frequent one in the latest 7 days of observed flights (not a schedule). The field is absent when no route is known. Any other value: 400, not counted.", "schema": { "type": "string", "enum": [ "route" ] } } ], "responses": { "200": { "description": "Matching aircraft.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AircraftList" } } } }, "400": { "description": "An invalid list option, not counted: an unknown name in `fields` (the body carries `allowed` and `presets`) or a `with` other than `route`. The body links the docs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v2/ladd": { "get": { "summary": "LADD aircraft", "description": "Aircraft whose dbFlags has the LADD bit (bit 3).", "tags": [ "live" ], "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Only these fields of each aircraft, comma-separated. `light` = hex, flight, r, t, lat, lon, alt_baro, gs, track, squawk, seen_pos, category (a fixed list). Presets and names can be mixed (`light,rssi`). `hex` is always present and first; a field the aircraft does not have is missing, as in the full record. An unknown name: 400 with `allowed` and `presets`, not counted. https://flyitalyadsb.com/en/data/api/docs/endpoints/#list-options", "schema": { "type": "string", "examples": [ "light", "hex,flight,lat,lon,alt_baro", "light,rssi" ] } }, { "name": "with", "in": "query", "required": false, "description": "`route` adds `route` to each aircraft whose callsign has a known route: the most frequent one in the latest 7 days of observed flights (not a schedule). The field is absent when no route is known. Any other value: 400, not counted.", "schema": { "type": "string", "enum": [ "route" ] } } ], "responses": { "200": { "description": "Matching aircraft.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AircraftList" } } } }, "400": { "description": "An invalid list option, not counted: an unknown name in `fields` (the body carries `allowed` and `presets`) or a `with` other than `route`. The body links the docs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v2/sqk/{squawk}": { "get": { "summary": "Aircraft by squawk", "description": "Aircraft squawking this code, network-wide. Alias: /v2/squawk/{squawk}.", "tags": [ "live" ], "parameters": [ { "name": "squawk", "in": "path", "required": true, "description": "4 octal digits, e.g. 7700.", "schema": { "type": "string", "pattern": "^[0-7]{4}$" } }, { "name": "fields", "in": "query", "required": false, "description": "Only these fields of each aircraft, comma-separated. `light` = hex, flight, r, t, lat, lon, alt_baro, gs, track, squawk, seen_pos, category (a fixed list). Presets and names can be mixed (`light,rssi`). `hex` is always present and first; a field the aircraft does not have is missing, as in the full record. An unknown name: 400 with `allowed` and `presets`, not counted. https://flyitalyadsb.com/en/data/api/docs/endpoints/#list-options", "schema": { "type": "string", "examples": [ "light", "hex,flight,lat,lon,alt_baro", "light,rssi" ] } }, { "name": "with", "in": "query", "required": false, "description": "`route` adds `route` to each aircraft whose callsign has a known route: the most frequent one in the latest 7 days of observed flights (not a schedule). The field is absent when no route is known. Any other value: 400, not counted.", "schema": { "type": "string", "enum": [ "route" ] } } ], "responses": { "200": { "description": "Matching aircraft.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AircraftList" } } } }, "400": { "description": "Invalid value, or an invalid list option; not counted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v2/squawk/{squawk}": { "get": { "summary": "Aircraft by squawk (alias of /v2/sqk)", "description": "Same as /v2/sqk/{squawk}.", "tags": [ "live" ], "parameters": [ { "name": "squawk", "in": "path", "required": true, "description": "4 octal digits, e.g. 7700.", "schema": { "type": "string", "pattern": "^[0-7]{4}$" } }, { "name": "fields", "in": "query", "required": false, "description": "Only these fields of each aircraft, comma-separated. `light` = hex, flight, r, t, lat, lon, alt_baro, gs, track, squawk, seen_pos, category (a fixed list). Presets and names can be mixed (`light,rssi`). `hex` is always present and first; a field the aircraft does not have is missing, as in the full record. An unknown name: 400 with `allowed` and `presets`, not counted. https://flyitalyadsb.com/en/data/api/docs/endpoints/#list-options", "schema": { "type": "string", "examples": [ "light", "hex,flight,lat,lon,alt_baro", "light,rssi" ] } }, { "name": "with", "in": "query", "required": false, "description": "`route` adds `route` to each aircraft whose callsign has a known route: the most frequent one in the latest 7 days of observed flights (not a schedule). The field is absent when no route is known. Any other value: 400, not counted.", "schema": { "type": "string", "enum": [ "route" ] } } ], "responses": { "200": { "description": "Matching aircraft.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AircraftList" } } } }, "400": { "description": "Invalid value, or an invalid list option; not counted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v2/type/{type}": { "get": { "summary": "Aircraft by ICAO type", "description": "Aircraft of this ICAO type designator, network-wide.", "tags": [ "live" ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "ICAO type designator, 2-4 letters or digits, case-insensitive, e.g. A320.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{2,4}$" } }, { "name": "fields", "in": "query", "required": false, "description": "Only these fields of each aircraft, comma-separated. `light` = hex, flight, r, t, lat, lon, alt_baro, gs, track, squawk, seen_pos, category (a fixed list). Presets and names can be mixed (`light,rssi`). `hex` is always present and first; a field the aircraft does not have is missing, as in the full record. An unknown name: 400 with `allowed` and `presets`, not counted. https://flyitalyadsb.com/en/data/api/docs/endpoints/#list-options", "schema": { "type": "string", "examples": [ "light", "hex,flight,lat,lon,alt_baro", "light,rssi" ] } }, { "name": "with", "in": "query", "required": false, "description": "`route` adds `route` to each aircraft whose callsign has a known route: the most frequent one in the latest 7 days of observed flights (not a schedule). The field is absent when no route is known. Any other value: 400, not counted.", "schema": { "type": "string", "enum": [ "route" ] } } ], "responses": { "200": { "description": "Matching aircraft.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AircraftList" } } } }, "400": { "description": "Invalid value, or an invalid list option; not counted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v2/airport/{code}/runways": { "get": { "summary": "The runway an airport is using now (estimate)", "description": "Estimated from the aircraft the network sees now within 25 km of the airport: an aircraft counts for a runway end when it is below 5,000 ft above the field, lined up within 20 degrees and within 1 km of the extended centreline, and either arriving (not climbing, up to 18 km before the threshold), departing (climbing, over the runway or up to 12 km after it) or rolling on it at 40 kt or more; with parallel runways the nearest centreline wins. An estimate, not an official source: a quiet airport can show no runway (empty in_use). Runways from OurAirports (public domain), refreshed nightly. One request. https://flyitalyadsb.com/en/data/api/docs/endpoints/#runway-in-use", "tags": [ "live" ], "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Airport ICAO (e.g. LIMC) or IATA (e.g. MXP) code.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The runways in use now, busiest first. Cacheable for 15 seconds.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunwaysInUse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown airport code (\"unknown airport code\"), or no runway data for this airport (\"no runway data for this airport\").", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "The runway data is not loaded yet (\"runway data is not available yet\"), or live data is briefly unavailable: retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/history/{icao}": { "get": { "summary": "Dates with a recorded track for one aircraft", "tags": [ "history" ], "parameters": [ { "name": "icao", "in": "path", "required": true, "description": "24-bit ICAO address, 6 hex characters.", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{6}$" } } ], "responses": { "200": { "description": "Sorted list of dates.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryDates" } } } }, "400": { "description": "icao is not 6 hex characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v2/history/{icao}/{date}": { "get": { "summary": "One aircraft's track for one day", "description": "readsb's trace_full file for that aircraft and day, passed through as written. From 2022-04-10 to 2023-10-04 the archive holds imported Virtual Radar Server data: only the first and last point of each flight (\"version\": \"vrs-basestation-import\"). The current day is built from readsb's live trace files (X-History-Source live), or from the overflights store once readsb no longer has the aircraft (store: position, altitude, flags, source and callsign only); it may answer 503 while a file is being written. With since, only the points after that time, the rest of the file unchanged (X-Since-Applied: 1). https://flyitalyadsb.com/en/data/api/docs/endpoints/#since", "tags": [ "history" ], "parameters": [ { "name": "icao", "in": "path", "required": true, "description": "24-bit ICAO address, 6 hex characters.", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{6}$" } }, { "name": "date", "in": "path", "required": true, "description": "UTC day, YYYY-MM-DD, not in the future.", "schema": { "type": "string", "format": "date" } }, { "name": "since", "in": "query", "required": false, "description": "Unix time in seconds: keep only the points with timestamp + offset > since. Milliseconds, negative or non-numeric values: 400, not counted. Empty = absent.", "schema": { "type": "number", "minimum": 0, "examples": [ 1794038400 ] } } ], "responses": { "200": { "description": "The trace.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" }, "X-History-Source": { "description": "Where the day was read from: `local` (the server), `r2` (the archive), `live` (today, readsb's live trace) or `store` (today, the overflights store).", "schema": { "type": "string", "enum": [ "local", "r2", "live", "store" ] } }, "X-Since-Applied": { "$ref": "#/components/headers/X-Since-Applied" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trace" } } } }, "400": { "description": "icao or date is malformed, the date is in the future, or since is not a Unix time in seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No trace for this aircraft on this date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "502": { "description": "The archived trace could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The archive is briefly unavailable, or today's file is being written: retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/profile/{icao}": { "get": { "summary": "Profile of one aircraft", "description": "Identity (registration, ICAO type, type description, year, decoded dbFlags), live status (position, callsign and position source when received now) and a history summary (first and last day with a track, days in the last 30 UTC days, total days; the same dates as /v2/history/{icao}), plus links to the public map and to a public photo page. One request. Never returns owner or operator names. No photo is embedded: Planespotters.net's API terms forbid re-serving their photos through another API, so `photos.page` is a link to their public page, and it is null (with `withheld`) for PIA and LADD aircraft.", "tags": [ "live", "history" ], "parameters": [ { "name": "icao", "in": "path", "required": true, "description": "24-bit ICAO address, 6 hex characters.", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{6}$" } } ], "responses": { "200": { "description": "The profile.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "400": { "description": "icao is not 6 hex characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Not received now and no recorded history for this aircraft.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Live data or the archive is briefly unavailable: retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/overflights": { "get": { "summary": "Aircraft that flew over a place in a time window", "description": "Every aircraft whose recorded track passed within `dist` km of the point between `from` and `to`, one entry per aircraft, sorted by the time of its closest point. Tracks are interpolated between received positions (gaps over 5 minutes are not). Covers the days since 2026-08-17, the current day up to about 10 minutes ago, and the periods not searched are listed in `coverage.gaps`. One request per call. The maximum `dist` and window depend on the plan (Free 10 km / 6 h, Starter 25 km / 24 h, others 50 km / 24 h): https://flyitalyadsb.com/en/data/api/#piani. Aircraft data only: registration, type, description and dbFlags, never the owner or operator.", "tags": [ "history" ], "parameters": [ { "name": "lat", "in": "query", "required": true, "description": "Latitude, decimal degrees.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon", "in": "query", "required": true, "description": "Longitude, decimal degrees.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "dist", "in": "query", "required": true, "description": "Radius in km.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 50 } }, { "name": "from", "in": "query", "required": true, "description": "Start: ISO 8601 (UTC when there is no offset) or Unix seconds.", "schema": { "type": "string", "examples": [ "2026-10-21T08:00:00Z" ] } }, { "name": "to", "in": "query", "required": true, "description": "End, after `from`: ISO 8601 or Unix seconds. A time in the future is cut to now.", "schema": { "type": "string", "examples": [ "2026-10-21T10:00:00Z" ] } }, { "name": "max_alt_ft", "in": "query", "required": false, "description": "Only the part of each track at or below this altitude (feet); positions without altitude are left out.", "schema": { "type": "number", "minimum": 0, "maximum": 100000 } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many aircraft.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "The overflights, with what was searched.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Overflights" } } } }, "400": { "description": "A parameter is missing or malformed, `to` is not after `from`, or the circle contains a pole.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "`dist` or the window is above the plan's maximum (the body carries max_dist_km and max_window_hours).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Too many searches at once, or the index is briefly unavailable: retry shortly (Retry-After).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/flights/callsign/{callsign}": { "get": { "summary": "Flight history of a callsign, and its usual routes", "description": "The flights of a callsign the network observed in the last days, newest first, and its usual routes (`usual`, with how many times each was flown). The callsign takes the same forms as /v2/callsign, so a flight number works too (matched_as/matched_value say which form matched). A callsign with no flights answers 200 with count 0. How far back `days` can go depends on the plan: https://flyitalyadsb.com/en/data/api/docs/endpoints/#observed-flights-depth. On Fleet the JSON answer also carries `today`: the flights since `since` (today, UTC), from takeoffs and landings detected in real time, with an estimated arrival time for an aircraft in flight; on other plans `today` is {available: false, error, plans}. These answers are cached privately for at most 15 seconds. https://flyitalyadsb.com/en/data/api/docs/endpoints/#todays-flights", "tags": [ "flights" ], "parameters": [ { "name": "callsign", "in": "path", "required": true, "description": "Callsign or flight number.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "How many days back, up to yesterday.", "schema": { "type": "integer", "minimum": 1, "maximum": 14, "default": 7 } } ], "responses": { "200": { "description": "The callsign's observed flights.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallsignFlights" } } } }, "400": { "description": "A parameter is malformed or out of range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FlightsDepth" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "The flights index is briefly unavailable: retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/flights/icao/{hex}": { "get": { "summary": "Flight history of one aircraft (flight log)", "description": "One aircraft's observed flights between two UTC days (default the last 7 available days, at most 31 per request), newest first, with a summary (flights, minutes, airports) for flight hours. An aircraft with no flights in the period answers 200 with count 0. `format=csv` returns the same flights as a CSV flight log (text/csv), one row per flight, oldest first. How far back `from` can go depends on the plan (403 code flights-depth beyond it, not counted): https://flyitalyadsb.com/en/data/api/docs/endpoints/#observed-flights-depth. On Fleet the JSON answer also carries `today`: the flights since `since` (today, UTC), from takeoffs and landings detected in real time, with an estimated arrival time for an aircraft in flight; on other plans `today` is {available: false, error, plans}. These answers are cached privately for at most 15 seconds. https://flyitalyadsb.com/en/data/api/docs/endpoints/#todays-flights", "tags": [ "flights" ], "parameters": [ { "name": "hex", "in": "path", "required": true, "description": "24-bit ICAO address, hex.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "First UTC day, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Last UTC day, YYYY-MM-DD (included).", "schema": { "type": "string", "format": "date" } }, { "name": "format", "in": "query", "required": false, "description": "`csv`: the flights as CSV, columns day, callsign, icao, r, t, from, from_iata, from_time_utc, from_seen, to, to_iata, to_time_utc, to_seen, duration_min; times UTC as YYYY-MM-DD HH:MM:SS, an end not observed leaves its columns empty.", "schema": { "type": "string", "enum": [ "csv" ] } } ], "responses": { "200": { "description": "The aircraft's observed flights.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AircraftFlights" } }, "text/csv": { "schema": { "type": "string" }, "example": "day,callsign,icao,r,t,from,from_iata,from_time_utc,from_seen,to,to_iata,to_time_utc,to_seen,duration_min\n" } } }, "400": { "description": "A parameter is malformed or out of range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FlightsDepth" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "The flights index is briefly unavailable: retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/flights/reg/{reg}": { "get": { "summary": "Flight history of one aircraft, by registration", "description": "One aircraft's observed flights between two UTC days (default the last 7 available days, at most 31 per request), newest first, with a summary (flights, minutes, airports) for flight hours. An aircraft with no flights in the period answers 200 with count 0. `format=csv` returns the same flights as a CSV flight log (text/csv), one row per flight, oldest first. How far back `from` can go depends on the plan (403 code flights-depth beyond it, not counted): https://flyitalyadsb.com/en/data/api/docs/endpoints/#observed-flights-depth. On Fleet the JSON answer also carries `today`: the flights since `since` (today, UTC), from takeoffs and landings detected in real time, with an estimated arrival time for an aircraft in flight; on other plans `today` is {available: false, error, plans}. These answers are cached privately for at most 15 seconds. https://flyitalyadsb.com/en/data/api/docs/endpoints/#todays-flights", "tags": [ "flights" ], "parameters": [ { "name": "reg", "in": "path", "required": true, "description": "Registration; case, spaces and dashes ignored.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "First UTC day, YYYY-MM-DD.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Last UTC day, YYYY-MM-DD (included).", "schema": { "type": "string", "format": "date" } }, { "name": "format", "in": "query", "required": false, "description": "`csv`: the flights as CSV, columns day, callsign, icao, r, t, from, from_iata, from_time_utc, from_seen, to, to_iata, to_time_utc, to_seen, duration_min; times UTC as YYYY-MM-DD HH:MM:SS, an end not observed leaves its columns empty.", "schema": { "type": "string", "enum": [ "csv" ] } } ], "responses": { "200": { "description": "The aircraft's observed flights.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AircraftFlights" } }, "text/csv": { "schema": { "type": "string" }, "example": "day,callsign,icao,r,t,from,from_iata,from_time_utc,from_seen,to,to_iata,to_time_utc,to_seen,duration_min\n" } } }, "400": { "description": "A parameter is malformed or out of range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FlightsDepth" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "The flights index is briefly unavailable: retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/flights/airport/{code}": { "get": { "summary": "Departures or arrivals observed at an airport on one day", "description": "The flights observed leaving (or reaching) an airport on one UTC day, sorted by time. How far back `date` can go depends on the plan: https://flyitalyadsb.com/en/data/api/docs/endpoints/#observed-flights-depth", "tags": [ "flights" ], "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Airport ICAO (e.g. EGLL) or IATA (e.g. LHR) code.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "departures or arrivals.", "schema": { "type": "string", "enum": [ "departures", "arrivals" ], "default": "departures" } }, { "name": "date", "in": "query", "required": false, "description": "UTC day, YYYY-MM-DD; default the latest day available.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "The departures or arrivals.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AirportFlights" } } } }, "400": { "description": "A parameter is malformed or out of range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FlightsDepth" }, "404": { "description": "Unknown airport code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "The flights index is briefly unavailable: retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/flights/route/{from}/{to}": { "get": { "summary": "Find a flight by route: the callsigns observed between two airports", "description": "For when the route and roughly the time are known but not the callsign (some airlines mostly fly callsigns that are not the flight number). The callsigns observed flying from one airport to the other in the last days, most flights first, each with its usual departure time (UTC, median), usual duration, last day, up to three aircraft and, when an aircraft with that callsign is flying now, its live record. Observed by the network, not airline schedules. https://flyitalyadsb.com/en/data/api/docs/endpoints/#find-my-flight", "tags": [ "flights" ], "parameters": [ { "name": "from", "in": "path", "required": true, "description": "Departure airport, ICAO or IATA code.", "schema": { "type": "string" } }, { "name": "to", "in": "path", "required": true, "description": "Arrival airport, ICAO or IATA code.", "schema": { "type": "string" } }, { "name": "around", "in": "query", "required": false, "description": "HH:MM, UTC: only the callsigns whose usual departure is within `window` minutes of it.", "schema": { "type": "string", "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$" } }, { "name": "window", "in": "query", "required": false, "description": "Minutes around `around`.", "schema": { "type": "integer", "minimum": 15, "maximum": 720, "default": 90 } }, { "name": "days", "in": "query", "required": false, "description": "How many days back, up to the latest available; the plan limits how far back.", "schema": { "type": "integer", "minimum": 1, "maximum": 14, "default": 7 } } ], "responses": { "200": { "description": "The callsigns observed on the route.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteFlights" } } } }, "400": { "description": "A parameter is malformed or out of range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/FlightsDepth" }, "404": { "description": "An IATA code we do not know.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "The flights index is briefly unavailable: retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/me/location": { "get": { "summary": "The position saved on the key's account", "description": "For \"aircraft near me\": the position the user saved (My API, or the MCP tool set_my_location), rounded to about 1 km. Not counted as a request. `location` is null when none is saved.", "tags": [ "account" ], "responses": { "200": { "description": "The saved position, or null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "summary": "Save the position on the key's account", "description": "Replaces any saved position. Stored rounded to 2 decimals (about 1 km). At most 10 changes a minute per key.", "tags": [ "account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lat", "lon" ], "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lon": { "type": "number", "minimum": -180, "maximum": 180 }, "label": { "type": "string", "maxLength": 80, "description": "A short name, e.g. \"Brescia\"." } } } } } }, "responses": { "200": { "description": "The saved position.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationResult" } } } }, "400": { "description": "lat or lon is missing or out of range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/me/location/clear": { "post": { "summary": "Delete the position saved on the key's account", "tags": [ "account" ], "responses": { "200": { "description": "Deleted (location is null).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/events": { "get": { "summary": "Emergencies and notable aircraft within a radius since a time", "description": "Events recorded by the network: emergencies (squawk 7500/7600/7700 or the ADS-B emergency status, not \"lifeguard\"), military aircraft and \"interesting\" aircraft (dbFlags bits 0 and 1). One event per aircraft, kind and ~0.5° grid cell it entered, so a long flight appears once per cell; a new event for the same cell only after 30 (emergency) or 60 minutes away. Newest first. Counted as one request; the plan's radius applies. https://flyitalyadsb.com/en/data/api/docs/alerts/", "tags": [ "events" ], "parameters": [ { "name": "lat", "in": "query", "required": true, "description": "Latitude, decimal degrees.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lon", "in": "query", "required": true, "description": "Longitude, decimal degrees.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "dist", "in": "query", "required": true, "description": "Radius in km.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 20040 } }, { "name": "since", "in": "query", "description": "Unix seconds or ISO 8601 (no zone = UTC). Default 24 hours ago, at most 7 days ago.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "description": "Unix seconds or ISO 8601. Default now.", "schema": { "type": "string" } }, { "name": "kinds", "in": "query", "description": "Comma-separated subset of emergency, military, interesting. Default all.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "At most this many events (1–500, default 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "Matching events.", "headers": { "X-FIA-Plan": { "$ref": "#/components/headers/X-FIA-Plan" }, "X-FIA-Used-Month": { "$ref": "#/components/headers/X-FIA-Used-Month" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } } }, "400": { "description": "A parameter is missing or out of range (the error says which).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The radius is above the plan's maximum (the body carries max_radius_km and a link to the plans).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Database unavailable, try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/webhooks": { "get": { "summary": "The account's webhooks", "description": "Never includes the signing secret. Not counted as a request (at most 20 webhook calls a minute per key).", "tags": [ "webhooks" ], "responses": { "200": { "description": "The webhooks, and the maximum per account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Database unavailable, try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a webhook", "description": "Paid plans only, at most 5 per account. The URL must be https on port 443 or 8443 and resolve only to public addresses. The answer carries the signing secret, shown this once. An area webhook has lat, lon and dist (capped by the plan's radius) and area kinds. A webhook for the watched aircraft (Fleet) has kinds takeoff and/or landing and no area: it receives flight.takeoff, flight.landing and flight.landing_retracted for every aircraft in /v2/watch. https://flyitalyadsb.com/en/data/api/docs/alerts/#aircraft", "tags": [ "webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Area webhook", "type": "object", "required": [ "url", "lat", "lon", "dist" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500 }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lon": { "type": "number", "minimum": -180, "maximum": 180 }, "dist": { "type": "number", "exclusiveMinimum": 0, "maximum": 20040, "description": "Radius in km." }, "kinds": { "type": "array", "items": { "enum": [ "emergency", "military", "interesting" ] }, "description": "Default [\"emergency\", \"military\"]." }, "description": { "type": "string", "maxLength": 200 } } }, { "title": "Watched aircraft webhook", "type": "object", "required": [ "url", "kinds" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500 }, "kinds": { "type": "array", "minItems": 1, "items": { "enum": [ "takeoff", "landing" ] }, "description": "No lat, lon or dist (400 with an area); not mixed with area kinds (400)." }, "landings": { "type": "string", "enum": [ "confirmed", "fast" ], "default": "confirmed", "description": "Landings deduced from the aircraft disappearing low near a field: confirmed waits 4 minutes and sends them only if the aircraft was not seen flying again (about 5% withdrawn later), fast sends them at once (about 17% withdrawn). Takeoffs and landings seen on the ground are sent at once either way." }, "description": { "type": "string", "maxLength": 200 } } } ] } } } }, "responses": { "201": { "description": "Created; store the secret now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }, "400": { "description": "Invalid JSON, url not allowed (code \"url-not-allowed\"), an area or kind out of range, an area on a takeoff/landing webhook, or takeoff/landing mixed with area kinds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Webhooks are for paid plans (code \"paid-plan-required\"); takeoff and landing webhooks are for the plan with watched aircraft, Fleet (code \"watch-plan-required\").", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The account already has the maximum number of webhooks (code \"webhook-limit\").", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Database unavailable, try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/webhooks/{id}/deliveries": { "get": { "summary": "A webhook's last 20 deliveries", "tags": [ "webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No webhook with this id for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Database unavailable, try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/webhooks/{id}/delete": { "post": { "summary": "Delete a webhook", "description": "Allowed on any plan. Pending deliveries are cancelled.", "tags": [ "webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted ({\"status\": \"ok\"}).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No webhook with this id for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Database unavailable, try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/webhooks/{id}/enable": { "post": { "summary": "Enable a webhook again after it was disabled", "description": "A webhook is disabled after 15 failed attempts in a row over at least an hour. This resets the count.", "tags": [ "webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Webhooks are for paid plans (code \"paid-plan-required\").", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No webhook with this id for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Database unavailable, try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/webhooks/{id}/test": { "post": { "summary": "Send a test delivery", "description": "Queues one `webhook.test` delivery, signed like the others, attempted once. See its outcome in /deliveries.", "tags": [ "webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "integer" } } ], "responses": { "202": { "description": "Queued ({\"delivery_id\", \"message\"}).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Webhooks are for paid plans (code \"paid-plan-required\").", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No webhook with this id for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The webhook is disabled (code \"disabled\"): enable it first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Database unavailable, try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/watch": { "get": { "summary": "The account's watched aircraft", "description": "The aircraft whose takeoffs and landings the account's flight webhooks receive, with the plan's max. Any plan. Not counted as a request (at most 20 webhook and watch calls a minute per key). https://flyitalyadsb.com/en/data/api/docs/alerts/#aircraft", "tags": [ "watch" ], "responses": { "200": { "description": "The watched aircraft.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Database unavailable, try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Watch aircraft", "description": "Adds up to 50 aircraft in one request, by ICAO address, registration or callsign. Fleet only (up to 25). An aircraft already on the list counts in already_watched. All or nothing: an invalid aircraft (400) or one over the plan's max (409) adds none. Not counted as a request. https://flyitalyadsb.com/en/data/api/docs/alerts/#aircraft", "tags": [ "watch" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "aircraft" ], "properties": { "aircraft": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "oneOf": [ { "type": "string", "description": "An ICAO address (6 hex digits; six hex characters are always read as one), a registration with a dash, space or dot inside (EI-DAC, EI DAC), or anything else without a separator, which matches as a registration or a callsign (N123AB, RYR5518)." }, { "type": "object", "description": "Exactly one of icao, reg or callsign, and an optional label that comes back in every alert.", "properties": { "icao": { "type": "string" }, "reg": { "type": "string" }, "callsign": { "type": "string", "description": "Also matches its flight-number form (FR5518 = RYR5518)." }, "label": { "type": "string", "maxLength": 60 } } } ] } } } }, "example": { "aircraft": [ "4D2247", "EI-DAC", { "callsign": "RYR5518", "label": "Stansted shuttle" } ] } } } }, "responses": { "200": { "description": "The list after adding, with added and already_watched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchList" } } } }, "400": { "description": "Invalid JSON, an empty list or more than 50, or an aircraft that is not an ICAO address, a registration or a callsign (code \"aircraft-invalid\").", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The plan has no watched aircraft (code \"watch-plan-required\", with plans): Fleet has them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "More aircraft than the plan allows (code \"watch-limit\"): nothing added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchLimitError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Database unavailable, try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/watch/remove": { "post": { "summary": "Stop watching aircraft", "description": "By aircraft, written as when adding, or by ids from the list. Any plan. Not counted as a request. https://flyitalyadsb.com/en/data/api/docs/alerts/#aircraft", "tags": [ "watch" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "aircraft": { "type": "array", "items": { "oneOf": [ { "type": "string", "description": "An ICAO address (6 hex digits; six hex characters are always read as one), a registration with a dash, space or dot inside (EI-DAC, EI DAC), or anything else without a separator, which matches as a registration or a callsign (N123AB, RYR5518)." }, { "type": "object", "description": "Exactly one of icao, reg or callsign, and an optional label that comes back in every alert.", "properties": { "icao": { "type": "string" }, "reg": { "type": "string" }, "callsign": { "type": "string", "description": "Also matches its flight-number form (FR5518 = RYR5518)." }, "label": { "type": "string", "maxLength": 60 } } } ] } }, "ids": { "type": "array", "items": { "type": "integer" } } } } } } }, "responses": { "200": { "description": "The list after removing, with removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchList" } } } }, "400": { "description": "Neither aircraft nor ids, or an aircraft that can't be read (code \"aircraft-invalid\").", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Database unavailable, try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/keys": { "post": { "summary": "Request an API key by email", "description": "Sends a one-time link (valid 7 days) to the address; opening it shows the key once. The key is never in this response or in the email. Requesting again for the same address rotates the self-serve key when the new link is used; until then the old key keeps working. One free key per mailbox (+tag and Gmail-dot variants count as the same mailbox); temporary email domains are refused.", "tags": [ "keys" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "found_via" ], "properties": { "email": { "type": "string", "format": "email", "description": "An address a person controls." }, "name": { "type": "string", "maxLength": 200, "description": "App, device or agent name." }, "use_case": { "type": "string", "maxLength": 500 }, "found_via": { "type": "string", "enum": [ "chatgpt", "claude", "perplexity", "gemini", "copilot", "other_ai", "search", "github", "api_list", "forum", "word_of_mouth", "feeder", "pypi", "other" ], "description": "Required. How you found FlyItalyADSB. An agent signing up for its user sends the assistant it is (e.g. claude, chatgpt); the official Python client sends pypi." }, "lang": { "type": "string", "enum": [ "it", "en" ], "default": "it", "description": "Language of the email." }, "audience": { "type": "string", "enum": [ "just_me", "my_product_users", "internal_org", "research", "other" ], "description": "Who the data is for. Accepted now and will become required: agents should send it already (ask the user rather than guess). Unknown value: 400, code \"audience-invalid\", with \"allowed\"." }, "audience_other": { "type": "string", "maxLength": 120, "description": "With audience \"other\": what." }, "other_source": { "type": "string", "enum": [ "none", "switching", "backup", "comparing" ], "description": "Whether another flight data source is already in use and what role this one will have: none (this is the first), switching (it becomes the main one), backup, comparing. Accepted now and will become required: agents should send it already. Unknown value: 400, code \"other-source-invalid\", with \"allowed\"." }, "other_source_name": { "type": "string", "maxLength": 120, "description": "With other_source other than \"none\": which source." }, "ai_prompt": { "type": "string", "maxLength": 300, "description": "Optional, kept only when found_via is an AI assistant (chatgpt, claude, perplexity, gemini, copilot, other_ai): what the user asked it." }, "options_order": { "type": "object", "description": "Site form only: the order in which the form showed the options.", "properties": { "audience": { "type": "array", "items": { "type": "string" } }, "other_source": { "type": "array", "items": { "type": "string" } } } } } } } } }, "responses": { "202": { "description": "Accepted: check the mailbox.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "ok" }, "message": { "type": "string" } } } } } }, "400": { "description": "Missing or invalid email, a temporary email domain (code \"disposable-email\"), a missing or unknown found_via (code \"found-via-required\", with the accepted codes in \"allowed\"), an unknown audience or other_source (codes \"audience-invalid\", \"other-source-invalid\"; once they are required, \"audience-required\", \"other-source-required\"), or invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A key was requested for this address a few minutes ago.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Database unavailable, try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "trafficEvent": { "post": { "summary": "A notable-traffic event, sent to your webhook URL", "description": "Signed with Standard Webhooks (https://www.standardwebhooks.com/): HMAC-SHA256 with the base64-decoded part of the secret after \"whsec_\", over \"{webhook-id}.{webhook-timestamp}.{raw body}\". Reject a timestamp more than 5 minutes away and dedupe on webhook-id, which is the same on every retry. Answer 2xx within 10 seconds; anything else (redirects included) is retried 6 times over about 5 hours. https://flyitalyadsb.com/en/data/api/docs/alerts/", "tags": [ "webhooks" ], "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "msg_, the same on every retry.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds of this attempt.", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "\"v1,\".", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx: delivered." } } } }, "flightAlert": { "post": { "summary": "A takeoff or landing of a watched aircraft, sent to a takeoff/landing webhook (Fleet)", "description": "Signed and retried like trafficEvent. Detected in real time from the network's receivers, best effort: a takeoff or landing the network does not see is not sent. One alert per aircraft and kind every 20 minutes (circuits). A landing deduced from the aircraft disappearing near a field comes about 2.5 minutes after its last signal; if the aircraft is seen flying again within 10 minutes, flight.landing_retracted follows (same event_id), only to the webhooks that got the landing. Events detected more than 15 minutes earlier are never sent. https://flyitalyadsb.com/en/data/api/docs/alerts/#aircraft", "tags": [ "webhooks" ], "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "msg_, the same on every retry.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds of this attempt.", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "\"v1,\".", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FlightAlertPayload" }, { "$ref": "#/components/schemas/FlightRetractPayload" } ] } } } }, "responses": { "200": { "description": "Any 2xx: delivered." } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Self-serve: https://flyitalyadsb.com/en/data/api/#api-key" } }, "headers": { "X-FIA-Plan": { "description": "The key's plan (free, feeder, starter, pro, fleet, enterprise).", "schema": { "type": "string" } }, "X-FIA-Used-Month": { "description": "Requests counted this month for the key.", "schema": { "type": "integer" } }, "X-Matched-As": { "description": "Present when the aircraft was found under another form of the identifier: callsign, reg or icao.", "schema": { "type": "string", "enum": [ "callsign", "reg", "icao" ] } }, "X-Matched-Value": { "description": "The form that matched, e.g. RYR5518 for FR5518, SP-GPM for SPGPM.", "schema": { "type": "string" } }, "X-Since-Applied": { "description": "1 when since was applied: only the points after it are in the trace. Absent: the file came whole.", "schema": { "type": "string", "const": "1" } } }, "responses": { "Unauthorized": { "description": "Missing or invalid X-Api-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Per-minute limit (key or, on Free, IP) or the plan's monthly quota. Per-minute answers carry Retry-After.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unavailable": { "description": "Live data is briefly unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "FlightsDepth": { "description": "Further back than the plan's observed-flights depth (code \"flights-depth\"); not counted. https://flyitalyadsb.com/en/data/api/docs/endpoints/#observed-flights-depth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlightsDepthError" } } } } }, "schemas": { "LookupNotFound": { "type": "object", "required": [ "error" ], "properties": { "error": { "const": "not found" }, "query": { "type": "string", "description": "/v2/find only: the text, cleaned." }, "tried": { "description": "The forms tried: a list for /v2/callsign and /v2/reg; for /v2/find an object (callsign list, reg, icao).", "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "additionalProperties": true } ] }, "hint": { "type": "string", "description": "Why it may not be found, e.g. a flight number is not always the callsign." }, "docs": { "type": "string", "format": "uri" }, "found_as": { "type": "object", "description": "The text is another identifier of an aircraft in the air: where to ask for it. Never another aircraft in place of the asked one.", "properties": { "matched_as": { "enum": [ "callsign", "reg", "icao" ] }, "value": { "type": "string" }, "path": { "type": "string" } } }, "last_seen": { "$ref": "#/components/schemas/Flight", "description": "The last flight observed for it in the past 7 days, when there is one." } }, "additionalProperties": true }, "FindResult": { "type": "object", "required": [ "query", "count", "results" ], "properties": { "query": { "type": "string" }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "matched_as": { "enum": [ "callsign", "reg", "icao" ] }, "value": { "type": "string", "description": "The form that matched." }, "aircraft": { "$ref": "#/components/schemas/Aircraft" } } } } } }, "FlightEnd": { "type": [ "object", "null" ], "description": "One end of an observed flight; null when it was not identified.", "properties": { "airport": { "type": "string", "description": "ICAO code (or the local code of a small airfield)." }, "iata": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2." }, "time": { "type": "integer", "description": "Unix seconds: when the network saw the aircraft at this end." }, "seen": { "enum": [ "ground", "low", "approach" ], "description": "How the airport was recognised: ground (on the ground within 6 km), low (at most 2,500 ft above it within 15 km), approach (at most 6,000 ft within 30 km, heading consistent). ground/low times are close to take-off or landing." } } }, "Flight": { "type": "object", "description": "A flight observed by the network, not an airline schedule. Never the owner or operator.", "properties": { "icao": { "type": "string" }, "r": { "type": [ "string", "null" ], "description": "Registration." }, "t": { "type": [ "string", "null" ], "description": "ICAO type code." }, "callsign": { "type": [ "string", "null" ] }, "from": { "$ref": "#/components/schemas/FlightEnd" }, "to": { "$ref": "#/components/schemas/FlightEnd" }, "first_seen": { "type": "integer", "description": "Unix seconds." }, "last_seen": { "type": "integer", "description": "Unix seconds." }, "duration_min": { "type": "integer", "description": "Observed minutes, first to last point." }, "day": { "type": "string", "format": "date", "description": "UTC day the flight started; flights across midnight UTC are joined." } } }, "FlightsCoverage": { "type": "object", "description": "The days searched; missing = days in the period that are not built (yet).", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "missing": { "type": "array", "items": { "type": "string", "format": "date" } } } }, "CallsignFlights": { "type": "object", "properties": { "callsign": { "type": "string" }, "matched_as": { "type": "string", "description": "Present when a translated form matched (e.g. a flight number)." }, "matched_value": { "type": "string" }, "days": { "type": "integer" }, "coverage": { "$ref": "#/components/schemas/FlightsCoverage" }, "usual": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "from_iata": { "type": [ "string", "null" ] }, "to": { "type": "string" }, "to_iata": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "last_day": { "type": "string", "format": "date" } } } }, "count": { "type": "integer" }, "flights": { "type": "array", "items": { "$ref": "#/components/schemas/Flight" } }, "today": { "$ref": "#/components/schemas/TodayFlights" } } }, "AircraftFlights": { "type": "object", "properties": { "icao": { "type": "string" }, "r": { "type": [ "string", "null" ] }, "coverage": { "$ref": "#/components/schemas/FlightsCoverage" }, "count": { "type": "integer" }, "summary": { "type": "object", "properties": { "flights": { "type": "integer" }, "minutes": { "type": "integer" }, "airports": { "type": "integer" } } }, "flights": { "type": "array", "items": { "$ref": "#/components/schemas/Flight" } }, "today": { "$ref": "#/components/schemas/TodayFlights" } } }, "TodayFlights": { "description": "Today's flights (JSON answers of /v2/flights/icao, /hex, /reg, /callsign). https://flyitalyadsb.com/en/data/api/docs/endpoints/#todays-flights", "oneOf": [ { "title": "Today (Fleet)", "type": "object", "required": [ "available", "since", "source", "count", "flights" ], "properties": { "available": { "const": true }, "since": { "type": "string", "format": "date", "description": "The first UTC day not in the nightly flights yet: today, or yesterday right after midnight UTC." }, "source": { "const": "live" }, "count": { "type": "integer" }, "flights": { "type": "array", "items": { "$ref": "#/components/schemas/TodayFlight" }, "description": "Oldest first." }, "note": { "type": "string" } } }, { "title": "Not available", "type": "object", "required": [ "available", "error" ], "properties": { "available": { "const": false }, "error": { "type": "string", "description": "Not in this plan, or briefly unavailable." }, "plans": { "type": [ "string", "null" ], "format": "uri", "description": "When the plan has no today's flights: where to choose one." } } } ] }, "TodayFlight": { "type": "object", "description": "A flight of today from takeoffs and landings detected in real time: one the network does not see is missing. Repeated takeoffs and landings (circuits) are each a flight.", "required": [ "icao", "from", "to", "status" ], "properties": { "icao": { "type": "string" }, "callsign": { "type": [ "string", "null" ] }, "from": { "oneOf": [ { "$ref": "#/components/schemas/TodayFlightEnd" }, { "type": "null" } ], "description": "null: a landing with no takeoff seen since `since`." }, "to": { "oneOf": [ { "$ref": "#/components/schemas/TodayFlightEnd" }, { "type": "null" } ] }, "status": { "enum": [ "landed", "in_flight", "unknown" ], "description": "unknown: a takeoff with no landing seen, and the aircraft is not flying now (or took off again)." }, "duration_min": { "type": "integer", "description": "Landed flights with both ends: takeoff to landing." }, "position": { "type": "object", "description": "in_flight only: where it is now.", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "alt_ft": { "type": [ "number", "null" ] }, "gs_kt": { "type": "number" }, "track": { "type": [ "number", "null" ] } } }, "eta": { "$ref": "#/components/schemas/FlightEta" } } }, "TodayFlightEnd": { "type": "object", "properties": { "airport": { "type": "string", "description": "ICAO code where there is one, otherwise the OurAirports code." }, "time": { "type": "string", "format": "date-time", "description": "UTC, ISO 8601 (not Unix seconds as in Flight)." }, "seen": { "enum": [ "ground", "low", "approach" ] }, "runway": { "type": [ "string", "null" ] }, "place": { "enum": [ "airport", "heliport" ] }, "near": { "type": "boolean", "description": "true when the aircraft was more than 2 km from it: \"near\" the airport." } } }, "FlightEta": { "type": "object", "description": "in_flight only, and only an estimate: the usual destination of the callsign in the observed flights (when its usual route leaves from today's takeoff airport) and the straight-line time at the current ground speed. Absent without a usual route or under 80 knots; late while the aircraft is still climbing; never a schedule.", "properties": { "airport": { "type": "string" }, "airport_iata": { "type": [ "string", "null" ] }, "time": { "type": "string", "format": "date-time" }, "minutes": { "type": "integer" }, "distance_km": { "type": "integer" }, "estimate": { "const": true }, "basis": { "type": "string" } } }, "AirportFlights": { "type": "object", "properties": { "airport": { "type": "object", "properties": { "code": { "type": "string" }, "iata": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } } }, "type": { "enum": [ "departures", "arrivals" ] }, "date": { "type": "string", "format": "date" }, "count": { "type": "integer" }, "flights": { "type": "array", "items": { "$ref": "#/components/schemas/Flight" } } } }, "RouteFlights": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/AirportRef" }, "to": { "$ref": "#/components/schemas/AirportRef" }, "days": { "type": "integer" }, "coverage": { "$ref": "#/components/schemas/FlightsCoverage" }, "count": { "type": "integer", "description": "How many callsigns (candidates may be cut at 50)." }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "callsign": { "type": [ "string", "null" ] }, "flights": { "type": "integer", "description": "Flights observed on the route in the period." }, "usual_departure_utc": { "type": "string", "description": "HH:MM, UTC: the median departure time." }, "usual_duration_min": { "type": "integer", "description": "The median observed duration." }, "last_day": { "type": "string", "format": "date" }, "aircraft": { "type": "array", "description": "Up to three aircraft that flew it most.", "items": { "type": "object", "properties": { "r": { "type": "string", "description": "Registration, or the ICAO address when unknown." }, "t": { "type": [ "string", "null" ] } } } }, "live": { "$ref": "#/components/schemas/Aircraft", "description": "Present when an aircraft with this callsign is flying now." } } } }, "note": { "type": "string" } } }, "AirportRef": { "type": "object", "properties": { "code": { "type": "string" }, "iata": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } } }, "RunwaysInUse": { "type": "object", "required": [ "airport", "now", "in_use", "runways" ], "properties": { "airport": { "$ref": "#/components/schemas/AirportRef" }, "now": { "type": "number", "description": "Time of the live data, Unix seconds." }, "in_use": { "type": "array", "items": { "type": "string" }, "description": "Runway ends with traffic now, busiest first; empty when none." }, "runways": { "type": "array", "items": { "type": "object", "properties": { "runway": { "type": "string", "description": "Runway end, e.g. 35R." }, "heading": { "type": "integer", "description": "Direction of travel on it, degrees true." }, "arrivals": { "type": "integer" }, "departures": { "type": "integer" }, "aircraft": { "type": "array", "items": { "type": "object", "properties": { "hex": { "type": "string" }, "flight": { "type": [ "string", "null" ] }, "kind": { "enum": [ "arrival", "departure" ] } } } } } } }, "aircraft_nearby": { "type": "integer", "description": "Aircraft with a position within 25 km." }, "known_runways": { "type": "array", "items": { "type": "string" }, "description": "The airport's open runway ends." }, "note": { "type": "string" } } }, "FlightsDepthError": { "type": "object", "required": [ "error", "code", "max_days", "requested_days" ], "properties": { "error": { "type": "string" }, "code": { "const": "flights-depth" }, "max_days": { "type": "integer", "description": "The plan's depth, in days back from today (UTC)." }, "requested_days": { "type": "integer", "description": "How far back the request asked." }, "docs": { "type": "string", "format": "uri" }, "plans": { "type": "string", "format": "uri" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "help": { "type": "string", "format": "uri", "description": "On 401, 403 and 429: the FAQ answer for this error." } }, "additionalProperties": true }, "TrafficEvent": { "type": "object", "description": "An event, plus the aircraft fields known at that moment with readsb's names (flight, r, t, desc, year, alt_baro, gs, track, squawk, emergency, category, dbFlags); `source` is readsb's position type. Never the owner or operator.", "required": [ "id", "kind", "hex", "time", "lat", "lon" ], "properties": { "id": { "type": "integer" }, "kind": { "enum": [ "emergency", "military", "interesting" ] }, "reason": { "enum": [ "general", "hijack", "radio_failure", "minimum_fuel", "downed" ], "description": "Emergencies only." }, "hex": { "type": "string" }, "time": { "type": "string", "format": "date-time", "description": "When the aircraft was seen entering the cell." }, "lat": { "type": "number" }, "lon": { "type": "number" }, "distance_km": { "type": "number", "description": "From the query point (or the webhook centre)." }, "source": { "type": "string", "description": "adsb_icao, mlat, …" }, "map": { "type": "string", "format": "uri", "description": "The aircraft on the live map." } }, "additionalProperties": true }, "EventList": { "type": "object", "required": [ "now", "since", "until", "count", "truncated", "events" ], "properties": { "now": { "type": "number" }, "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "center": { "type": "object", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } } }, "dist": { "type": "number" }, "kinds": { "type": "array", "items": { "type": "string" } }, "count": { "type": "integer" }, "truncated": { "type": "boolean", "description": "More events matched than limit." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/TrafficEvent" } } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "integer" }, "for": { "enum": [ "area", "aircraft" ], "description": "aircraft: a takeoff and landing webhook for the watched aircraft, with no area." }, "url": { "type": "string" }, "lat": { "type": [ "number", "null" ] }, "lon": { "type": [ "number", "null" ] }, "dist": { "type": [ "number", "null" ] }, "kinds": { "type": "array", "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] }, "status": { "enum": [ "active", "disabled", "paused-plan" ], "description": "paused-plan: the account has no paid key now." }, "created_at": { "type": "string", "format": "date-time" }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "disabled_reason": { "type": [ "string", "null" ] }, "consecutive_failures": { "type": "integer" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "pending_deliveries": { "type": "integer" } } }, "WebhookList": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "max": { "type": "integer" } } }, "WebhookResult": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" } } }, "WebhookCreated": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" }, "secret": { "type": "string", "description": "whsec_…, shown only in this answer." }, "message": { "type": "string" } } }, "DeliveryList": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string", "description": "event.emergency, event.military, event.interesting, flight.takeoff, flight.landing, flight.landing_retracted, webhook.test" }, "event_id": { "type": [ "integer", "null" ] }, "status": { "enum": [ "pending", "sending", "delivered", "failed", "expired", "dropped", "cancelled" ] }, "attempts": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "next_attempt_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_status": { "type": [ "integer", "null" ], "description": "HTTP status of the last attempt." }, "last_error": { "type": [ "string", "null" ] }, "last_duration_ms": { "type": [ "integer", "null" ] } } } } } }, "WatchEntry": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "enum": [ "icao", "reg", "callsign", "any" ], "description": "any: a value that matches as a registration or a callsign." }, "value": { "type": "string", "description": "Without separators; the ICAO address in lower case." }, "label": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "WatchList": { "type": "object", "required": [ "aircraft", "count", "max" ], "properties": { "aircraft": { "type": "array", "items": { "$ref": "#/components/schemas/WatchEntry" } }, "count": { "type": "integer" }, "max": { "type": "integer", "description": "The plan's maximum: Fleet 25, Enterprise 250, other plans 0." }, "added": { "type": "integer", "description": "On add." }, "already_watched": { "type": "integer", "description": "On add." }, "removed": { "type": "integer", "description": "On remove." }, "docs": { "type": "string", "format": "uri" } } }, "WatchLimitError": { "type": "object", "required": [ "error", "code", "max", "count", "adding" ], "properties": { "error": { "type": "string" }, "code": { "const": "watch-limit" }, "max": { "type": "integer" }, "count": { "type": "integer", "description": "Watched now." }, "adding": { "type": "integer", "description": "New aircraft in this request." }, "docs": { "type": "string", "format": "uri" } } }, "FlightAlertAircraft": { "type": "object", "properties": { "icao": { "type": "string" }, "registration": { "type": [ "string", "null" ] }, "callsign": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "description": "ICAO type designator." }, "helicopter": { "type": "boolean" } } }, "FlightAlertPayload": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "enum": [ "flight.takeoff", "flight.landing" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "detected_at." }, "data": { "type": "object", "properties": { "webhook_id": { "type": "integer" }, "event_id": { "type": "integer" }, "kind": { "enum": [ "takeoff", "landing" ] }, "time": { "type": "string", "format": "date-time", "description": "When it happened; for a landing deduced from the aircraft disappearing, its last signal." }, "detected_at": { "type": "string", "format": "date-time" }, "aircraft": { "$ref": "#/components/schemas/FlightAlertAircraft" }, "airport": { "type": "string", "description": "ICAO code where there is one, otherwise the OurAirports code." }, "place": { "enum": [ "airport", "heliport" ] }, "distance_km": { "type": [ "number", "null" ] }, "near": { "type": "boolean", "description": "true beyond 2 km: \"near\" the airport, not \"at\"." }, "seen": { "enum": [ "ground", "low", "approach" ] }, "runway": { "type": [ "string", "null" ] }, "position": { "type": "object", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "alt_ft": { "type": [ "integer", "null" ] }, "gs_kt": { "type": [ "number", "null" ] }, "track": { "type": [ "number", "null" ] } } }, "watch": { "type": "object", "description": "The entry of the list that matched.", "properties": { "kind": { "type": "string" }, "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } } }, "map": { "type": "string", "format": "uri" } } } } }, "FlightRetractPayload": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "flight.landing_retracted" }, "timestamp": { "type": "string", "format": "date-time", "description": "retracted_at." }, "data": { "type": "object", "properties": { "webhook_id": { "type": "integer" }, "event_id": { "type": "integer", "description": "The event_id of the flight.landing it withdraws." }, "kind": { "const": "landing" }, "time": { "type": "string", "format": "date-time" }, "retracted_at": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "description": "reappeared: the aircraft was seen flying again." }, "aircraft": { "$ref": "#/components/schemas/FlightAlertAircraft" }, "airport": { "type": "string" }, "message": { "type": "string" } } } } }, "WebhookPayload": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "enum": [ "event.emergency", "event.military", "event.interesting", "webhook.test" ] }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "description": "The event (TrafficEvent, with webhook_id and distance_km from the webhook centre), or {webhook_id, message} for a test.", "$ref": "#/components/schemas/TrafficEvent" } } }, "LocationResult": { "type": "object", "required": [ "location" ], "properties": { "location": { "type": [ "object", "null" ], "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "label": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "Aircraft": { "type": "object", "description": "A record from readsb's aircraft.json. Which fields are present depends on what was received; only common ones are listed.", "required": [ "hex" ], "properties": { "hex": { "type": "string", "description": "ICAO address; a leading ~ marks a non-ICAO (e.g. TIS-B) address." }, "type": { "type": "string", "description": "Source of the current position, e.g. adsb_icao, mlat, tisb_icao." }, "flight": { "type": "string", "description": "Callsign, space-padded." }, "r": { "type": "string", "description": "Registration (aircraft database)." }, "t": { "type": "string", "description": "ICAO type code (aircraft database)." }, "dbFlags": { "type": "integer", "description": "Bits: 0 military, 1 interesting, 2 PIA, 3 LADD." }, "lat": { "type": "number" }, "lon": { "type": "number" }, "alt_baro": { "oneOf": [ { "type": "number" }, { "const": "ground" } ], "description": "Barometric altitude in feet, or \"ground\"." }, "alt_geom": { "type": "number", "description": "Geometric altitude, feet." }, "gs": { "type": "number", "description": "Ground speed, knots." }, "track": { "type": "number", "description": "True track, degrees." }, "baro_rate": { "type": "number", "description": "Vertical rate, ft/min." }, "squawk": { "type": "string" }, "seen": { "type": "number", "description": "Seconds since the last message." }, "seen_pos": { "type": "number", "description": "Seconds since the last position." }, "mlat": { "type": "array", "items": { "type": "string" }, "description": "Fields derived from MLAT." }, "route": { "$ref": "#/components/schemas/ObservedRoute" } }, "additionalProperties": true }, "ObservedRoute": { "type": "object", "description": "Only with with=route on a list: the most frequent route of the callsign in the latest 7 days of observed flights. Absent when unknown. Not a schedule.", "properties": { "from": { "type": "string", "description": "ICAO code." }, "from_iata": { "type": [ "string", "null" ] }, "to": { "type": "string", "description": "ICAO code." }, "to_iata": { "type": [ "string", "null" ] }, "count": { "type": "integer", "description": "Times flown in those days." }, "last_day": { "type": "string", "format": "date" }, "source": { "const": "observed" } } }, "AircraftList": { "type": "object", "required": [ "now", "count", "ac" ], "properties": { "now": { "type": "number", "description": "Server time, Unix seconds." }, "count": { "type": "integer" }, "total": { "type": "integer", "description": "Same as count, the field name of ADSBx v2." }, "ac": { "type": "array", "items": { "$ref": "#/components/schemas/Aircraft" } } } }, "MultiAircraftList": { "type": "object", "required": [ "now", "count", "total", "ac", "not_found", "matched" ], "properties": { "now": { "type": "number", "description": "Server time, Unix seconds." }, "count": { "type": "integer" }, "total": { "type": "integer" }, "ac": { "type": "array", "items": { "$ref": "#/components/schemas/Aircraft" }, "description": "The aircraft in the air now; one found by two values appears once." }, "not_found": { "type": "array", "items": { "type": "string" }, "description": "The values with no aircraft in the air now, as written." }, "matched": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Value as written -> the form found, only when they differ." } } }, "HistoryDates": { "type": "object", "required": [ "icao", "count", "dates" ], "properties": { "icao": { "type": "string" }, "count": { "type": "integer" }, "dates": { "type": "array", "items": { "type": "string", "format": "date" } }, "archive_unavailable": { "type": "boolean", "description": "Present when the archive could not be listed: only recent days are included." } } }, "Profile": { "type": "object", "required": [ "icao", "identity", "live", "history", "links", "photos" ], "properties": { "icao": { "type": "string" }, "identity": { "type": "object", "properties": { "registration": { "type": [ "string", "null" ] }, "icao_type": { "type": [ "string", "null" ], "description": "ICAO type designator, e.g. A319." }, "type_description": { "type": [ "string", "null" ] }, "year": { "type": [ "integer", "null" ], "description": "Year of manufacture, when the aircraft database has it." }, "db_flags": { "type": "integer", "description": "Bits: 0 military, 1 interesting, 2 PIA, 3 LADD." }, "military": { "type": "boolean" }, "interesting": { "type": "boolean" }, "pia": { "type": "boolean" }, "ladd": { "type": "boolean" }, "trace_day": { "type": [ "string", "null" ], "format": "date", "description": "The day whose track supplied type_description and year." } } }, "live": { "type": "object", "required": [ "seen_now" ], "description": "When seen_now is true, also: now, callsign, source (adsb_icao, mlat, tisb_icao…) and the aircraft.json fields lat, lon, alt_baro, alt_geom, gs, track, baro_rate, squawk, emergency, category, seen, seen_pos, mlat.", "properties": { "seen_now": { "type": "boolean" }, "now": { "type": "number", "description": "Time of the live data, Unix seconds." }, "callsign": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ], "description": "Source of the current position." } }, "additionalProperties": true }, "history": { "type": "object", "properties": { "first_day": { "type": [ "string", "null" ], "format": "date" }, "last_day": { "type": [ "string", "null" ], "format": "date" }, "days_last_30": { "type": "integer", "description": "Days with a track among today and the previous 29 (UTC)." }, "total_days": { "type": "integer" }, "archive_unavailable": { "type": "boolean", "description": "Present when the archive could not be listed: recent days only." } } }, "links": { "type": "object", "properties": { "map": { "type": [ "string", "null" ], "format": "uri", "description": "The public map on this aircraft: live, or its last track the map can show." }, "history": { "type": "string", "format": "uri" } } }, "photos": { "type": "object", "properties": { "page": { "type": [ "string", "null" ], "format": "uri", "description": "Public photo page on Planespotters.net (no image in this API)." }, "provider": { "type": "string" }, "withheld": { "type": [ "string", "null" ], "enum": [ "pia", "ladd", null ], "description": "Why there is no photo link." } } } } }, "Overflights": { "type": "object", "required": [ "count", "truncated", "coverage", "overflights" ], "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "dist_km": { "type": "number" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "max_alt_ft": { "type": [ "number", "null" ] }, "count": { "type": "integer" }, "truncated": { "type": "boolean", "description": "More passes exist than were returned." }, "complete_until": { "type": [ "string", "null" ], "format": "date-time", "description": "When truncated: every pass whose closest_time is before this is listed. Ask again from here." }, "coverage": { "type": "object", "properties": { "complete": { "type": "boolean" }, "gaps": { "type": "array", "description": "Periods NOT searched (not indexed yet, not covered, or tracks that could not be read).", "items": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "reason": { "type": "string" } } } } } }, "candidates": { "type": "integer", "description": "Aircraft examined." }, "overflights": { "type": "array", "items": { "$ref": "#/components/schemas/Overflight" } } } }, "Overflight": { "type": "object", "properties": { "icao": { "type": "string" }, "r": { "type": [ "string", "null" ], "description": "Registration." }, "t": { "type": [ "string", "null" ], "description": "ICAO type code." }, "desc": { "type": [ "string", "null" ] }, "dbFlags": { "type": "integer" }, "callsigns": { "type": "array", "items": { "type": "string" } }, "closest_time": { "type": "string", "format": "date-time" }, "closest_ts": { "type": "number", "description": "Unix seconds." }, "closest_km": { "type": "number" }, "closest_alt_ft": { "oneOf": [ { "type": "number" }, { "const": "ground" }, { "type": "null" } ] }, "min_alt_ft": { "oneOf": [ { "type": "number" }, { "const": "ground" }, { "type": "null" } ], "description": "Lowest altitude inside the circle." }, "entered": { "type": "string", "format": "date-time" }, "left": { "type": "string", "format": "date-time" }, "passes": { "type": "integer", "description": "Separate times it entered the circle." }, "positions": { "type": "integer", "description": "Received positions inside the circle; 0 = interpolated between positions outside it." }, "source": { "type": "string", "enum": [ "adsb", "mlat", "tisb", "other" ], "description": "Source of the closest position." }, "sources": { "type": "array", "items": { "type": "string" } }, "history": { "type": "array", "items": { "type": "string" }, "description": "The /v2/history paths of the days read." } } }, "Trace": { "type": "object", "description": "readsb trace_full JSON: icao, timestamp, and trace (array of points relative to timestamp), plus aircraft metadata.", "properties": { "icao": { "type": "string" }, "timestamp": { "type": "number" }, "trace": { "type": "array", "items": { "type": "array" } } }, "additionalProperties": true } } } }