FlyItalyADSB History API

Tracks: per-aircraft daily tracks, every day since 2023-03-03 except 2026-05-05 and 2026-05-06, and the first and last point of each flight from 2022-04-10; and the aircraft that flew over a place (since 2026-08-17).

GitHub OpenAPI

Operations 4

GET /v2/history/{icao} Dates with a recorded track for one aircraft #
GET /v2/history/{icao}/{date} One aircraft's track for one day #
GET /v2/profile/{icao} Profile of one aircraft #
GET /v2/overflights Aircraft that flew over a place in a time window #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/flyitalyadsb:flyitalyadsb-history-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

flyitalyadsb-history-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: FlyItalyADSB History 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 network of receivers run by volunteers (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. PIA and LADD aircraft are flagged in the dbFlags bit field (value 4 for PIA, 8 for LADD), so your product can hide them where its market or app store requires. Every endpoint except the key signup needs an X-Api-Key; keys are self-serve (see /auth.md). Plans and limits: https://flyitalyadsb.com/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/data/api/docs/adsbx-v2/. Operated by Nesso Labs S.r.l. (ISO/IEC 27001:2022, QMSCERT 160426-7).'
  termsOfService: https://flyitalyadsb.com/terms/
  contact:
    name: Nesso Labs S.r.l. (FlyItalyADSB)
    email: info@flyitalyadsb.com
    url: https://flyitalyadsb.com/contact/
  license:
    name: 'Data: CC BY-SA 4.0'
    url: https://creativecommons.org/licenses/by-sa/4.0/
servers:
- url: https://api.flyitalyadsb.com
security:
- ApiKey: []
tags:
- name: History
  description: 'Tracks: per-aircraft daily tracks, every day since 2023-03-03 except 2026-05-05 and 2026-05-06, and the first and last point of each flight from 2022-04-10; and the aircraft that flew over a place (since 2026-08-17).'
paths:
  /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'
      operationId: getV2HistoryByIcao
      x-operation-id-source: derived
  /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 also holds imported Virtual Radar Server data: only the first and last point of each flight ("version": "vrs-basestation-import"). From 2023-03-03 that file is returned only when there is no full track for that aircraft and day. 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/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'
      operationId: getV2HistoryByIcaoByDate
      x-operation-id-source: derived
  /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:
      - 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'
      operationId: getV2ProfileByIcao
      x-operation-id-source: derived
  /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/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'
      operationId: getV2Overflights
      x-operation-id-source: derived
components:
  schemas:
    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.'
    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
    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
    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.
  headers:
    X-FIA-Plan:
      description: The key's plan (free, feeder, starter, pro, fleet, enterprise).
      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'
    X-FIA-Used-Month:
      description: Requests counted this month for the key.
      schema:
        type: integer
  responses:
    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'
    Unauthorized:
      description: Missing or invalid X-Api-Key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: 'Self-serve: https://flyitalyadsb.com/data/api/#api-key'
externalDocs:
  description: 'API page: plans, endpoints, free key'
  url: https://flyitalyadsb.com/data/api/