openapi: 3.1.0
info:
  title: Flightradar24 Airlines Live Positions API
  description: Flightradar24 is the world's most popular real-time flight tracking platform, monitoring over 250,000 daily flights using data from a global network of ADS-B, MLAT, and radar receivers. The FR24 API provides developers with programmatic access to live aircraft positions, historical flight data, flight summaries, and reference data for airports and airlines. The credit-based subscription API uses Bearer token authentication and is available at https://fr24api.flightradar24.com/api with three tiers — Explorer, Essential, and Advanced — covering hobby projects through high-volume commercial applications.
  version: 1.0.0
  contact:
    url: https://support.fr24.com/support/solutions/folders/3000022922
  license:
    name: Proprietary
    url: https://fr24api.flightradar24.com/docs/getting-started
servers:
- url: https://fr24api.flightradar24.com/api
  description: Flightradar24 API
security:
- bearerAuth: []
tags:
- name: Live Positions
  description: Real-time aircraft position data
paths:
  /live/flight-positions/light:
    get:
      operationId: getLiveFlightPositionsLight
      summary: Get live flight positions (light)
      description: Returns a lightweight snapshot of real-time aircraft positions worldwide, including latitude, longitude, altitude, speed, heading, callsign, and aircraft registration. Optimised for mapping use cases that require low-latency positional data without the full set of flight metadata. At least one filter parameter is required.
      tags:
      - Live Positions
      parameters:
      - $ref: '#/components/parameters/bounds'
      - $ref: '#/components/parameters/flights'
      - $ref: '#/components/parameters/callsigns'
      - $ref: '#/components/parameters/registrations'
      - $ref: '#/components/parameters/painted_as'
      - $ref: '#/components/parameters/operating_as'
      - $ref: '#/components/parameters/airports'
      - $ref: '#/components/parameters/routes'
      - $ref: '#/components/parameters/aircraft'
      - $ref: '#/components/parameters/altitude_ranges'
      - $ref: '#/components/parameters/squawks'
      - $ref: '#/components/parameters/categories'
      - $ref: '#/components/parameters/data_sources'
      - $ref: '#/components/parameters/airspaces'
      - $ref: '#/components/parameters/gspeed'
      - $ref: '#/components/parameters/limit_30000'
      responses:
        '200':
          description: Successful response with live flight position data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightPositionsLightResponse'
              example:
                data:
                - fr24_id: 34242a02
                  lat: 51.4706
                  lon: -0.4619
                  track: 270
                  alt: 35000
                  gspeed: 450
                  vspeed: 0
                  squawk: '7700'
                  timestamp: '2024-01-15T10:30:00Z'
                  source: ADSB
                  hex: 400A10
                  callsign: BAW123
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /live/flight-positions/full:
    get:
      operationId: getLiveFlightPositionsFull
      summary: Get live flight positions (full)
      description: Returns complete real-time aircraft flight movement records including latitude, longitude, speed, altitude, and heading alongside enriched flight information such as origin and destination airports, callsign, aircraft registration, aircraft type, operator, and flight number. At least one filter parameter is required.
      tags:
      - Live Positions
      parameters:
      - $ref: '#/components/parameters/bounds'
      - $ref: '#/components/parameters/flights'
      - $ref: '#/components/parameters/callsigns'
      - $ref: '#/components/parameters/registrations'
      - $ref: '#/components/parameters/painted_as'
      - $ref: '#/components/parameters/operating_as'
      - $ref: '#/components/parameters/airports'
      - $ref: '#/components/parameters/routes'
      - $ref: '#/components/parameters/aircraft'
      - $ref: '#/components/parameters/altitude_ranges'
      - $ref: '#/components/parameters/squawks'
      - $ref: '#/components/parameters/categories'
      - $ref: '#/components/parameters/data_sources'
      - $ref: '#/components/parameters/airspaces'
      - $ref: '#/components/parameters/gspeed'
      - $ref: '#/components/parameters/limit_30000'
      responses:
        '200':
          description: Successful response with full live flight position data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightPositionsFullResponse'
              example:
                data:
                - fr24_id: 34242a02
                  lat: 51.4706
                  lon: -0.4619
                  track: 270
                  alt: 35000
                  gspeed: 450
                  vspeed: 0
                  squawk: '7700'
                  timestamp: '2024-01-15T10:30:00Z'
                  source: ADSB
                  flight: BA123
                  callsign: BAW123
                  hex: 400A10
                  type: B77W
                  reg: G-STBK
                  painted_as: BAW
                  operating_as: BAW
                  orig_iata: LHR
                  orig_icao: EGLL
                  dest_iata: JFK
                  dest_icao: KJFK
                  eta: '2024-01-15T15:45:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /live/flight-positions/count:
    get:
      operationId: getLiveFlightPositionsCount
      summary: Count live flight positions
      description: Returns the number of live aircraft positions that match the given filters. At least one filter parameter is required.
      tags:
      - Live Positions
      parameters:
      - $ref: '#/components/parameters/bounds'
      - $ref: '#/components/parameters/flights'
      - $ref: '#/components/parameters/callsigns'
      - $ref: '#/components/parameters/registrations'
      - $ref: '#/components/parameters/painted_as'
      - $ref: '#/components/parameters/operating_as'
      - $ref: '#/components/parameters/airports'
      - $ref: '#/components/parameters/routes'
      - $ref: '#/components/parameters/aircraft'
      - $ref: '#/components/parameters/altitude_ranges'
      - $ref: '#/components/parameters/squawks'
      - $ref: '#/components/parameters/categories'
      - $ref: '#/components/parameters/data_sources'
      - $ref: '#/components/parameters/gspeed'
      responses:
        '200':
          description: Successful response with count of matching records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountResponse'
              example:
                record_count: 1247
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    FlightPositionsLight:
      type: object
      description: Lightweight real-time or historical aircraft position data point.
      required:
      - fr24_id
      - lat
      - lon
      - track
      - alt
      - gspeed
      - vspeed
      - squawk
      - timestamp
      - source
      properties:
        fr24_id:
          type: string
          description: Flightradar24 unique identifier for the flight (hexadecimal).
          example: 34242a02
        lat:
          type: number
          format: float
          description: Latitude in decimal degrees.
          example: 51.4706
        lon:
          type: number
          format: float
          description: Longitude in decimal degrees.
          example: -0.4619
        track:
          type: integer
          description: True heading in degrees (0-360).
          example: 270
        alt:
          type: integer
          description: Altitude in feet.
          example: 35000
        gspeed:
          type: integer
          description: Ground speed in knots.
          example: 450
        vspeed:
          type: integer
          description: Vertical speed in feet per minute.
          example: 0
        squawk:
          type: string
          description: Transponder squawk code (4-digit octal).
          example: '7700'
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 date-time of the position fix.
          example: '2024-01-15T10:30:00Z'
        source:
          type: string
          description: Data source (e.g., ADSB, MLAT, RADAR).
          example: ADSB
        hex:
          type: string
          description: ICAO 24-bit aircraft address in hexadecimal (Mode S hex code).
          nullable: true
          example: 400A10
        callsign:
          type: string
          description: ATC callsign.
          nullable: true
          example: BAW123
    CountResponse:
      type: object
      description: Generic count response.
      required:
      - record_count
      properties:
        record_count:
          type: integer
          description: Number of records matching the query filters.
          example: 1247
    FlightPositionsLightResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FlightPositionsLight'
    FlightPositionsFullResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FlightPositionsFull'
    FlightPositionsFull:
      type: object
      description: Detailed real-time or historical aircraft position data point with full flight metadata.
      required:
      - fr24_id
      - lat
      - lon
      - track
      - alt
      - gspeed
      - vspeed
      - squawk
      - timestamp
      - source
      properties:
        fr24_id:
          type: string
          description: Flightradar24 unique identifier for the flight (hexadecimal).
          example: 34242a02
        lat:
          type: number
          format: float
          description: Latitude in decimal degrees.
          example: 51.4706
        lon:
          type: number
          format: float
          description: Longitude in decimal degrees.
          example: -0.4619
        track:
          type: integer
          description: True heading in degrees (0-360).
          example: 270
        alt:
          type: integer
          description: Altitude in feet.
          example: 35000
        gspeed:
          type: integer
          description: Ground speed in knots.
          example: 450
        vspeed:
          type: integer
          description: Vertical speed in feet per minute.
          example: 0
        squawk:
          type: string
          description: Transponder squawk code (4-digit octal).
          example: '7700'
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 date-time of the position fix.
          example: '2024-01-15T10:30:00Z'
        source:
          type: string
          description: Data source (e.g., ADSB, MLAT, RADAR).
          example: ADSB
        flight:
          type: string
          description: Flight number (e.g., "BA123").
          nullable: true
          example: BA123
        callsign:
          type: string
          description: ATC callsign.
          nullable: true
          example: BAW123
        hex:
          type: string
          description: ICAO 24-bit aircraft address in hexadecimal.
          nullable: true
          example: 400A10
        type:
          type: string
          description: ICAO aircraft type code (e.g., "B77W", "A320").
          nullable: true
          example: B77W
        reg:
          type: string
          description: Aircraft registration number.
          nullable: true
          example: G-STBK
        painted_as:
          type: string
          description: Airline ICAO code for the livery carrier.
          nullable: true
          example: BAW
        operating_as:
          type: string
          description: Airline ICAO code for the operating carrier.
          nullable: true
          example: BAW
        orig_iata:
          type: string
          description: Origin airport IATA code.
          nullable: true
          example: LHR
        orig_icao:
          type: string
          description: Origin airport ICAO code.
          nullable: true
          example: EGLL
        dest_iata:
          type: string
          description: Destination airport IATA code.
          nullable: true
          example: JFK
        dest_icao:
          type: string
          description: Destination airport ICAO code.
          nullable: true
          example: KJFK
        eta:
          type: string
          format: date-time
          description: Estimated time of arrival (ISO 8601).
          nullable: true
          example: '2024-01-15T15:45:00Z'
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error description.
        code:
          type: string
          description: Machine-readable error code.
  parameters:
    operating_as:
      name: operating_as
      in: query
      required: false
      description: Comma-separated list of airline ICAO codes for the operating carrier. Maximum 15 values.
      schema:
        type: string
      example: BAW,DLH
    airports:
      name: airports
      in: query
      required: false
      description: Comma-separated list of airport IATA or ICAO codes. Matches flights departing or arriving at these airports. Maximum 15 values.
      schema:
        type: string
      example: LHR,EDDF
    flights:
      name: flights
      in: query
      required: false
      description: Comma-separated list of flight numbers (e.g., "BA123,LH456"). Maximum 15 values.
      schema:
        type: string
      example: BA123,LH456
    airspaces:
      name: airspaces
      in: query
      required: false
      description: Comma-separated list of airspace identifiers. Maximum 15 values. Not available on count endpoints.
      schema:
        type: string
      example: EGTT,EGPX
    limit_30000:
      name: limit
      in: query
      required: false
      description: Maximum number of records to return (1-30000).
      schema:
        type: integer
        minimum: 1
        maximum: 30000
      example: 1000
    categories:
      name: categories
      in: query
      required: false
      description: Comma-separated list of aircraft/vehicle category codes. Maximum 15 values. P=Passenger, C=Cargo, M=Military and Government, J=Business Jets, T=General Aviation, H=Helicopters, B=Lighter than Air, G=Gliders, D=Drones, V=Ground Vehicles, O=Other, N=Non-Categorized.
      schema:
        type: string
        enum:
        - P
        - C
        - M
        - J
        - T
        - H
        - B
        - G
        - D
        - V
        - O
        - N
      example: P,C
    routes:
      name: routes
      in: query
      required: false
      description: Comma-separated list of routes in origin-destination format (e.g., "LHR-JFK"). Maximum 15 values.
      schema:
        type: string
      example: LHR-JFK,CDG-LAX
    registrations:
      name: registrations
      in: query
      required: false
      description: Comma-separated list of aircraft registration codes (e.g., "G-STBK,D-ABCD"). Maximum 15 values.
      schema:
        type: string
      example: G-STBK,D-ABCD
    squawks:
      name: squawks
      in: query
      required: false
      description: Comma-separated list of transponder squawk codes (4-digit octal, e.g., "7700,7600"). Maximum 15 values.
      schema:
        type: string
      example: 7700,7600
    callsigns:
      name: callsigns
      in: query
      required: false
      description: Comma-separated list of ATC callsigns (e.g., "BAW123,DLH456"). Maximum 15 values.
      schema:
        type: string
      example: BAW123,DLH456
    altitude_ranges:
      name: altitude_ranges
      in: query
      required: false
      description: Comma-separated altitude ranges in feet using "min-max" format (e.g., "0-5000,35000-45000"). Minimum altitude is -2000 ft. Maximum 15 ranges.
      schema:
        type: string
      example: 0-5000,35000-45000
    aircraft:
      name: aircraft
      in: query
      required: false
      description: ICAO aircraft type code (e.g., "B77W", "A320").
      schema:
        type: string
      example: B77W
    bounds:
      name: bounds
      in: query
      required: false
      description: Geographic bounding box in the format "north,south,west,east" (e.g., "51.5,51.0,-0.5,0.5"). Latitudes range -90 to 90; longitudes -180 to 180. North must be greater than south.
      schema:
        type: string
        pattern: ^-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?$
      example: 51.5,51.0,-0.5,0.5
    gspeed:
      name: gspeed
      in: query
      required: false
      description: Ground speed filter in knots (0-5000), or a range string (e.g., "200-400").
      schema:
        oneOf:
        - type: integer
          minimum: 0
          maximum: 5000
        - type: string
      example: 200-400
    painted_as:
      name: painted_as
      in: query
      required: false
      description: Comma-separated list of airline ICAO codes for the livery carrier (e.g., "BAW,DLH"). Maximum 15 values.
      schema:
        type: string
      example: BAW,DLH
    data_sources:
      name: data_sources
      in: query
      required: false
      description: Comma-separated list of data source types (e.g., "ADSB,MLAT"). Maximum 15 values.
      schema:
        type: string
      example: ADSB,MLAT
  responses:
    BadRequest:
      description: Bad request — invalid or missing parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too many requests — rate limit or credit limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized — missing or invalid Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Obtain your API token from the Flightradar24 developer portal at https://fr24api.flightradar24.com/.