openapi: 3.1.0 info: title: Flightradar24 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 - name: Historic Positions description: Historical aircraft position data (back to May 11, 2016) - name: Historic Events description: Historical flight event data (takeoff, landing, gate movements, airspace transitions) - name: Flight Summary description: Synopses of individual flights including event timings and key identifiers - name: Flight Tracks description: Full positional track of a specific flight by FR24 flight ID - name: Airports description: Reference data for airports worldwide - name: Airlines description: Reference data for airlines - name: Usage description: API account usage and credit consumption 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' /historic/flight-positions/light: get: operationId: getHistoricFlightPositionsLight summary: Get historical flight positions (light) description: >- Provides historical aircraft positional data using Unix timestamp. Returns lightweight position records (latitude, longitude, altitude, speed, heading, callsign, registration) for past flights. Historical data coverage extends back to May 11, 2016, with availability depending on the subscription plan. A timestamp and at least one additional filter parameter are required. tags: - Historic Positions parameters: - $ref: '#/components/parameters/timestamp_required' - $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' - $ref: '#/components/parameters/limit_30000' responses: '200': description: Successful response with historical light flight position data content: application/json: schema: $ref: '#/components/schemas/FlightPositionsLightResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' /historic/flight-positions/full: get: operationId: getHistoricFlightPositionsFull summary: Get historical flight positions (full) description: >- Returns full historical aircraft flight movement records for a given time window, combining positional data with enriched flight metadata including origin, destination, callsign, registration, aircraft type, and operator. Data is accessible back to May 11, 2016 depending on the subscription tier. Available on Essential and Advanced plans. A timestamp and at least one additional filter parameter are required. tags: - Historic Positions parameters: - $ref: '#/components/parameters/timestamp_required' - $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' - $ref: '#/components/parameters/limit_30000' responses: '200': description: Successful response with historical full flight position data content: application/json: schema: $ref: '#/components/schemas/FlightPositionsFullResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' /historic/flight-positions/count: get: operationId: getHistoricFlightPositionsCount summary: Count historical flight positions description: >- Returns the number of historical aircraft positions that match the given filters. A timestamp and at least one additional filter parameter are required. tags: - Historic Positions parameters: - $ref: '#/components/parameters/timestamp_required' - $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 historical records content: application/json: schema: $ref: '#/components/schemas/CountResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' /historic/flight-events/light: get: operationId: getHistoricFlightEventsLight summary: Get historical flight events (light) description: >- Returns comprehensive historical information on flight events including takeoff, landing, gate movements, and airspace transitions. Lightweight version includes fr24_id, callsign, hex, and events list. tags: - Historic Events parameters: - name: flight_ids in: query required: true description: >- Comma-separated FR24 flight IDs (hexadecimal). Maximum 15 IDs. Example: "391fdd79,35f2ffd9" schema: type: string example: "391fdd79,35f2ffd9" - name: event_types in: query required: true description: >- Comma-separated event types to filter by. Use "all" to return all event types. schema: type: string enum: - all - gate_departure - takeoff - cruising - airspace_transition - descent - diverting - diverted - landed - gate_arrival example: "gate_departure,takeoff,landed" responses: '200': description: Successful response with historical flight events (light) content: application/json: schema: $ref: '#/components/schemas/FlightEventsLightResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' /historic/flight-events/full: get: operationId: getHistoricFlightEventsFull summary: Get historical flight events (full) description: >- Returns comprehensive historical information on flight events including takeoff, landing, gate movements, and airspace transitions, with additional flight and aircraft details such as origin, destination, and aircraft type. tags: - Historic Events parameters: - name: flight_ids in: query required: true description: >- Comma-separated FR24 flight IDs (hexadecimal). Maximum 15 IDs. schema: type: string example: "391fdd79,35f2ffd9" - name: event_types in: query required: true description: >- Comma-separated event types to filter by. Use "all" to return all event types. schema: type: string example: "all" responses: '200': description: Successful response with historical flight events (full) content: application/json: schema: $ref: '#/components/schemas/FlightEventsFullResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' /flight-summary/light: get: operationId: getFlightSummaryLight summary: Get flight summaries (light) description: >- Returns lightweight synopses of individual flights including key event timings and locations such as actual takeoff and landing times, departure and arrival airports, and primary flight, aircraft, and operator identifiers. Available in both near-real-time and historical modes. Either flight_ids or a time range (flight_datetime_from + flight_datetime_to) must be provided. tags: - Flight Summary parameters: - $ref: '#/components/parameters/flight_ids' - $ref: '#/components/parameters/flight_datetime_from' - $ref: '#/components/parameters/flight_datetime_to' - $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_list' - $ref: '#/components/parameters/categories' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/limit_20000' responses: '200': description: Successful response with light flight summary data content: application/json: schema: $ref: '#/components/schemas/FlightSummaryLightResponse' example: data: - fr24_id: "391fdd79" flight: "BA456" callsign: "BAW456" operating_as: "BAW" painted_as: "BAW" type: "A320" reg: "G-EUUU" orig_icao: "EGLL" datetime_takeoff: "2024-01-15T08:30:00" dest_icao: "EDDF" dest_icao_actual: "EDDF" datetime_landed: "2024-01-15T10:45:00" hex: "400A20" first_seen: "2024-01-15T08:25:00" last_seen: "2024-01-15T10:50:00" flight_ended: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' /flight-summary/full: get: operationId: getFlightSummaryFull summary: Get flight summaries (full) description: >- Returns full synopses of individual flights combining positional event data with enriched metadata including runway designators, flight time, actual distances, and complete airport codes (IATA and ICAO). Either flight_ids or a time range must be provided. tags: - Flight Summary parameters: - $ref: '#/components/parameters/flight_ids' - $ref: '#/components/parameters/flight_datetime_from' - $ref: '#/components/parameters/flight_datetime_to' - $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_list' - $ref: '#/components/parameters/categories' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/limit_20000' responses: '200': description: Successful response with full flight summary data content: application/json: schema: $ref: '#/components/schemas/FlightSummaryFullResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' /flight-summary/count: get: operationId: getFlightSummaryCount summary: Count flight summaries description: >- Returns the number of flight summary records matching the given filters. Either flight_ids or a time range must be provided. tags: - Flight Summary parameters: - $ref: '#/components/parameters/flight_ids' - $ref: '#/components/parameters/flight_datetime_from' - $ref: '#/components/parameters/flight_datetime_to' - $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_list' - $ref: '#/components/parameters/categories' responses: '200': description: Successful response with count of matching flight summaries content: application/json: schema: $ref: '#/components/schemas/CountResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' /flight-tracks: get: operationId: getFlightTracks summary: Get flight tracks description: >- Returns the full positional track of a specific flight identified by its FR24 flight ID. Provides a time-ordered sequence of latitude, longitude, altitude, speed, and heading records spanning the entire flight from departure to arrival. tags: - Flight Tracks parameters: - name: flight_id in: query required: true description: >- Flightradar24 ID of the flight in hexadecimal format (e.g., "34242a02"). schema: type: string pattern: '^[0-9a-f]{8}$' example: "34242a02" responses: '200': description: Successful response with flight track data content: application/json: schema: $ref: '#/components/schemas/FlightTracksResponse' example: data: - fr24_id: "34242a02" tracks: - timestamp: "2024-01-15T08:00:00Z" lat: 51.4706 lon: -0.4619 alt: 0 gspeed: 0 vspeed: 0 track: 270 squawk: "2000" callsign: "BAW123" source: "ADSB" - timestamp: "2024-01-15T08:15:00Z" lat: 51.5074 lon: -0.1278 alt: 15000 gspeed: 350 vspeed: 1800 track: 270 squawk: "2000" callsign: "BAW123" source: "ADSB" '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' /static/airports/{code}/light: get: operationId: getAirportLight summary: Get airport (light) description: >- Returns basic reference data for an airport by IATA or ICAO code, including the airport name, IATA code, and ICAO code. tags: - Airports parameters: - name: code in: path required: true description: Airport IATA (3-letter) or ICAO (4-letter) code. schema: type: string pattern: '^([A-Z]{3}|[A-Z]{4})$' example: "LHR" responses: '200': description: Successful response with basic airport data content: application/json: schema: $ref: '#/components/schemas/AirportLight' example: icao: "EGLL" iata: "LHR" name: "London Heathrow Airport" '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' /static/airports/{code}/full: get: operationId: getAirportFull summary: Get airport (full) description: >- Returns detailed reference data for an airport by IATA or ICAO code, including full airport name, geographic coordinates, elevation, country, city, state, timezone, and runway information. tags: - Airports parameters: - name: code in: path required: true description: Airport IATA (3-letter) or ICAO (4-letter) code. schema: type: string pattern: '^([A-Z]{3}|[A-Z]{4})$' example: "WAW" responses: '200': description: Successful response with detailed airport data content: application/json: schema: $ref: '#/components/schemas/AirportFull' example: name: "Warsaw Chopin Airport" lat: 52.1657 lon: 20.9671 elevation: 110.5 country: code: "PL" name: "Poland" city: "Warsaw" state: "Masovian Voivodeship" timezone: name: "Europe/Warsaw" offset: 3600 iata: "WAW" icao: "EPWA" runways: - designator: "15/33" heading: 150 length: 3690 width: 60 elevation: 110 thr_coordinates: [52.1657, 20.9671] surface: type: "ASPH" description: "Asphalt" '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' /static/airlines/{icao}/light: get: operationId: getAirlineLight summary: Get airline (light) description: >- Returns basic reference data for an airline by ICAO code, including airline name, IATA code, and ICAO code. Useful for resolving callsign prefixes and operator codes present in flight data into human-readable airline names. tags: - Airlines parameters: - name: icao in: path required: true description: Airline ICAO code (3-letter), e.g., "SAS", "DLH", "BAW". schema: type: string pattern: '^[A-Z]{3}$' example: "BAW" responses: '200': description: Successful response with basic airline data content: application/json: schema: $ref: '#/components/schemas/AirlineLight' example: name: "British Airways" icao: "BAW" iata: "BA" '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' /usage: get: operationId: getUsage summary: Get API usage description: >- Returns a summary of API account usage and credit consumption broken down by endpoint for the specified time period. tags: - Usage parameters: - name: period in: query required: false description: Time period for the usage summary. schema: type: string enum: - 24h - 7d - 30d - 1y default: 24h example: "24h" responses: '200': description: Successful response with API usage data content: application/json: schema: $ref: '#/components/schemas/UsageLogSummaryResponse' example: data: - endpoint: "/api/live/flight-positions/light" request_count: 142 credits: 284 - endpoint: "/api/flight-summary/full" request_count: 38 credits: 380 '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer token authentication. Obtain your API token from the Flightradar24 developer portal at https://fr24api.flightradar24.com/. parameters: 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" 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" 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" 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" 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" 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" 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" aircraft: name: aircraft in: query required: false description: ICAO aircraft type code (e.g., "B77W", "A320"). schema: type: string example: "B77W" aircraft_list: name: aircraft in: query required: false description: >- Comma-separated list of ICAO aircraft type codes (e.g., "B77W,A320"). Maximum 15 values. schema: type: string example: "B77W,A320" 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" 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" 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" 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" 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" 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" 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 limit_20000: name: limit in: query required: false description: Maximum number of records to return (1-20000). schema: type: integer minimum: 1 maximum: 20000 example: 1000 timestamp_required: name: timestamp in: query required: true description: >- Unix timestamp (seconds since epoch) for the historical snapshot. Must be after 2016-05-11T00:00:00Z (Unix timestamp 1462924800). schema: type: integer minimum: 1462924800 example: 1705312200 flight_ids: name: flight_ids in: query required: false description: >- Comma-separated FR24 flight IDs (hexadecimal format). Maximum 15 IDs. schema: type: string example: "391fdd79,35f2ffd9" flight_datetime_from: name: flight_datetime_from in: query required: false description: >- Start of the date-time range for filtering flights (ISO 8601 format, e.g., "2024-01-15T00:00:00"). Either flight_ids or a date range is required. schema: type: string format: date-time example: "2024-01-15T00:00:00" flight_datetime_to: name: flight_datetime_to in: query required: false description: >- End of the date-time range for filtering flights (ISO 8601 format, e.g., "2024-01-15T23:59:59"). schema: type: string format: date-time example: "2024-01-15T23:59:59" sort: name: sort in: query required: false description: >- Sort order for results. Use field name for ascending, prefix with "-" for descending (e.g., "datetime_takeoff" or "-datetime_takeoff"). schema: type: string example: "-datetime_takeoff" 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" FlightPositionsLightResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/FlightPositionsLight' 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" FlightPositionsFullResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/FlightPositionsFull' FlightSummaryLight: type: object description: Lightweight flight summary record. required: - fr24_id properties: fr24_id: type: string description: Flightradar24 unique identifier for the flight. example: "391fdd79" flight: type: string nullable: true description: Flight number. example: "BA456" callsign: type: string nullable: true description: ATC callsign. example: "BAW456" operating_as: type: string nullable: true description: Airline ICAO code for the operating carrier. example: "BAW" painted_as: type: string nullable: true description: Airline ICAO code for the livery carrier. example: "BAW" type: type: string nullable: true description: ICAO aircraft type code. example: "A320" reg: type: string nullable: true description: Aircraft registration. example: "G-EUUU" orig_icao: type: string nullable: true description: Departure airport ICAO code. example: "EGLL" datetime_takeoff: type: string nullable: true description: Actual takeoff date-time (YYYY-MM-DDTHH:MM:SS). example: "2024-01-15T08:30:00" dest_icao: type: string nullable: true description: Planned destination airport ICAO code. example: "EDDF" dest_icao_actual: type: string nullable: true description: Actual destination airport ICAO code (may differ if diverted). example: "EDDF" datetime_landed: type: string nullable: true description: Actual landing date-time (YYYY-MM-DDTHH:MM:SS). example: "2024-01-15T10:45:00" hex: type: string nullable: true description: ICAO 24-bit aircraft address in hexadecimal. example: "400A20" first_seen: type: string nullable: true description: Date-time when the flight first appeared on radar. example: "2024-01-15T08:25:00" last_seen: type: string nullable: true description: Date-time when the flight last appeared on radar. example: "2024-01-15T10:50:00" flight_ended: type: boolean nullable: true description: Whether the flight has completed. example: true FlightSummaryLightResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/FlightSummaryLight' FlightSummaryFull: type: object description: Detailed flight summary record with runway, distance, and timing data. required: - fr24_id properties: fr24_id: type: string description: Flightradar24 unique identifier for the flight. example: "391fdd79" flight: type: string nullable: true example: "BA456" callsign: type: string nullable: true example: "BAW456" operating_as: type: string nullable: true example: "BAW" painted_as: type: string nullable: true example: "BAW" type: type: string nullable: true example: "A320" reg: type: string nullable: true example: "G-EUUU" orig_icao: type: string nullable: true example: "EGLL" orig_iata: type: string nullable: true example: "LHR" datetime_takeoff: type: string nullable: true example: "2024-01-15T08:30:00" runway_takeoff: type: string nullable: true description: Departure runway designator. example: "27L" dest_icao: type: string nullable: true example: "EDDF" dest_iata: type: string nullable: true example: "FRA" dest_icao_actual: type: string nullable: true example: "EDDF" dest_iata_actual: type: string nullable: true example: "FRA" datetime_landed: type: string nullable: true example: "2024-01-15T10:45:00" runway_landed: type: string nullable: true description: Arrival runway designator. example: "25R" flight_time: type: number format: float nullable: true description: Flight duration in seconds. example: 8100.0 actual_distance: type: number format: float nullable: true description: Actual distance flown in kilometres. example: 638.5 circle_distance: type: number format: float nullable: true description: Great-circle (direct) distance in kilometres. example: 630.0 category: type: string nullable: true description: Flight category code. example: "P" hex: type: string nullable: true example: "400A20" first_seen: type: string nullable: true example: "2024-01-15T08:25:00" last_seen: type: string nullable: true example: "2024-01-15T10:50:00" flight_ended: type: boolean nullable: true example: true FlightSummaryFullResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/FlightSummaryFull' FlightTrackPoint: type: object description: A single positional point in a flight track. required: - timestamp - lat - lon - alt - gspeed - vspeed - track - squawk - source properties: timestamp: type: string format: date-time description: ISO 8601 date-time of the position fix. example: "2024-01-15T08:15:00Z" lat: type: number format: float description: Latitude in decimal degrees. example: 51.5074 lon: type: number format: float description: Longitude in decimal degrees. example: -0.1278 alt: type: integer description: Altitude in feet. example: 15000 gspeed: type: integer description: Ground speed in knots. example: 350 vspeed: type: integer description: Vertical speed in feet per minute. example: 1800 track: type: integer description: True heading in degrees (0-360). example: 270 squawk: type: string description: Transponder squawk code. example: "2000" callsign: type: string nullable: true description: ATC callsign. example: "BAW123" source: type: string description: Data source (e.g., ADSB, MLAT, RADAR). example: "ADSB" FlightTracks: type: object description: Complete positional track for a single flight. required: - fr24_id properties: fr24_id: type: string description: Flightradar24 unique identifier for the flight. example: "34242a02" tracks: type: array description: Time-ordered list of positional track points. items: $ref: '#/components/schemas/FlightTrackPoint' FlightTracksResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/FlightTracks' GateDetails: type: object description: Details for gate departure or arrival events. properties: gate_ident: type: string nullable: true description: Gate identifier. example: "B42" gate_lat: type: number format: float nullable: true description: Gate latitude. gate_lon: type: number format: float nullable: true description: Gate longitude. TakeoffDetails: type: object description: Details for takeoff events. properties: takeoff_runway: type: string nullable: true description: Takeoff runway designator. example: "27L" LandingDetails: type: object description: Details for landing events. properties: landed_icao: type: string nullable: true description: ICAO code of the airport where the aircraft landed. example: "EGLL" landed_runway: type: string nullable: true description: Landing runway designator. example: "27R" AirspaceDetails: type: object description: Details for airspace transition events. properties: exited_airspace: type: string nullable: true description: Name of the airspace exited. example: "EGTT" exited_airspace_id: type: string nullable: true description: ID of the airspace exited. entered_airspace: type: string nullable: true description: Name of the airspace entered. example: "EGPX" entered_airspace_id: type: string nullable: true description: ID of the airspace entered. FlightEvent: type: object description: A single flight event with position and event-specific details. required: - type - timestamp properties: type: type: string description: Event type. enum: - gate_departure - takeoff - cruising - airspace_transition - descent - diverting - diverted - landed - gate_arrival example: "takeoff" timestamp: type: string format: date-time description: ISO 8601 date-time when the event occurred. example: "2024-01-15T08:35:00Z" lat: type: number format: float nullable: true description: Latitude at event time. lon: type: number format: float nullable: true description: Longitude at event time. alt: type: integer nullable: true description: Altitude in feet at event time. gspeed: type: integer nullable: true description: Ground speed in knots at event time. details: nullable: true oneOf: - $ref: '#/components/schemas/GateDetails' - $ref: '#/components/schemas/TakeoffDetails' - $ref: '#/components/schemas/LandingDetails' - $ref: '#/components/schemas/AirspaceDetails' FlightEventsLight: type: object description: Lightweight historical flight events for a single flight. required: - fr24_id properties: fr24_id: type: string description: Flightradar24 unique identifier for the flight. example: "391fdd79" callsign: type: string nullable: true example: "BAW456" hex: type: string nullable: true description: ICAO 24-bit aircraft address in hexadecimal. example: "400A20" events: type: array items: $ref: '#/components/schemas/FlightEvent' FlightEventsLightResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/FlightEventsLight' FlightEventsFull: type: object description: Detailed historical flight events with full flight metadata. required: - fr24_id properties: fr24_id: type: string description: Flightradar24 unique identifier for the flight. example: "391fdd79" callsign: type: string nullable: true example: "BAW456" hex: type: string nullable: true example: "400A20" operating_as: type: string nullable: true description: Airline ICAO code for the operating carrier. example: "BAW" painted_as: type: string nullable: true description: Airline ICAO code for the livery carrier. example: "BAW" orig_iata: type: string nullable: true description: Origin airport IATA code. example: "LHR" orig_icao: type: string nullable: true description: Origin airport ICAO code. example: "EGLL" dest_iata: type: string nullable: true description: Destination airport IATA code. example: "JFK" dest_icao: type: string nullable: true description: Destination airport ICAO code. example: "KJFK" events: type: array items: $ref: '#/components/schemas/FlightEvent' FlightEventsFullResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/FlightEventsFull' AirportLight: type: object description: Basic airport reference data. required: - icao properties: icao: type: string description: Airport ICAO code. example: "EGLL" iata: type: string nullable: true description: Airport IATA code. example: "LHR" name: type: string nullable: true description: Airport full name. example: "London Heathrow Airport" Timezone: type: object required: - name - offset properties: name: type: string description: IANA timezone name. example: "Europe/London" offset: type: integer description: UTC offset in seconds. example: 0 Country: type: object required: - code - name properties: code: type: string description: ISO 3166-1 alpha-2 country code. example: "GB" name: type: string description: Country name. example: "United Kingdom" Surface: type: object required: - type - description properties: type: type: string description: Surface type code (e.g., ASPH, CONC, GRVL). example: "ASPH" description: type: string description: Human-readable surface description. example: "Asphalt" Runway: type: object required: - designator - heading - length - width - elevation - thr_coordinates - surface properties: designator: type: string description: Runway designator (e.g., "27L/09R"). example: "27L/09R" heading: type: integer description: Magnetic heading in degrees. example: 270 length: type: integer description: Runway length in metres. example: 3901 width: type: integer description: Runway width in metres. example: 60 elevation: type: integer description: Runway elevation in feet. example: 83 thr_coordinates: type: array description: Threshold coordinates [latitude, longitude]. items: type: number minItems: 2 maxItems: 2 example: [51.4706, -0.4619] surface: $ref: '#/components/schemas/Surface' AirportFull: type: object description: Detailed airport reference data including runways and geographic information. required: - name - lat - lon - elevation - country - city - timezone properties: name: type: string description: Airport full name. example: "London Heathrow Airport" lat: type: number format: float description: Airport latitude in decimal degrees. example: 51.4706 lon: type: number format: float description: Airport longitude in decimal degrees. example: -0.4619 elevation: type: number format: float description: Airport elevation in feet. example: 83.0 country: $ref: '#/components/schemas/Country' city: type: string description: City served by the airport. example: "London" timezone: $ref: '#/components/schemas/Timezone' iata: type: string nullable: true description: Airport IATA code. example: "LHR" icao: type: string nullable: true description: Airport ICAO code. example: "EGLL" state: type: string nullable: true description: State or region. example: "England" runways: type: array nullable: true description: List of runways at the airport. items: $ref: '#/components/schemas/Runway' AirlineLight: type: object description: Basic airline reference data. required: - name - icao properties: name: type: string description: Airline full name. example: "British Airways" icao: type: string description: Airline ICAO code. example: "BAW" iata: type: string nullable: true description: Airline IATA code. example: "BA" UsageLogSummary: type: object description: API usage summary for a single endpoint. required: - endpoint - request_count - credits properties: endpoint: type: string description: API endpoint path. example: "/api/live/flight-positions/light" request_count: type: integer description: Number of requests made to this endpoint in the period. example: 142 credits: type: integer description: Number of credits consumed by requests to this endpoint. example: 284 UsageLogSummaryResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/UsageLogSummary' 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 Error: type: object properties: message: type: string description: Human-readable error description. code: type: string description: Machine-readable error code. responses: BadRequest: description: Bad request — invalid or missing parameters. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized — missing or invalid Bearer token. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not found — the requested resource does not exist. 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'