FlightRadarAPI Rust SDK

A modern Rust SDK for FlightRadar24 focused on a typed, async, and testable developer experience.

[!IMPORTANT] This crate targets a robust SDK baseline first: strict payload parsing, resilient HTTP transport, typed domain errors, and deterministic mocked tests.

[!TIP] GitHub automatically shows an Outline (table of contents) for this README in the right panel.

Why This SDK

• Async-first API based on Tokio
• Strict response parsing with schema fallback support
• Retry and Cloudflare-aware transport behavior
• Strongly typed options for common flight and airport workflows
• Fully mocked integration tests (no flaky live network dependency)

Architecture

flowchart TD
  A[Consumer App] --> B[FlightRadarApi]
  B --> C[FlightRadarClient]
  C --> D[Reqwest HTTP Layer]
  D --> E[FlightRadar24 Endpoints]

  E --> F[Raw JSON Payload]
  F --> G[Typed Models + from_value Parsers]
  G --> H[Domain Responses]

  C --> I[Retry Backoff]
  C --> J[Cloudflare 520 Mapping]
  C --> K[Cookie Session Store]

Installation

cargo add flightradarapi

Run local examples:

cargo run --example quickstart

cargo run --example airport_lookup

Quickstart

[!NOTE] The example below uses a minimal airline filter and returns typed flight data.

use flightradarapi::{FlightQuery, FlightRadarApi};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
  let api = FlightRadarApi::new()?;

  let query = FlightQuery {
    airline: Some("AFR".to_owned()),
    with_details: false,
    ..Default::default()
  };

  let flights = api.get_flights(&query).await?;
  println!("flights returned: {}", flights.items().len());

  Ok(())
}

Local Quality Gates

cargo fmt --all

cargo clippy --all-targets --all-features -- -D warnings

cargo test --all-targets --all-features

[!WARNING] Keep -D warnings in CI to prevent silent quality regressions.

API Coverage (MVP+)

• Flights: get_flights, get_flight_details, get_history_data
• Airports: get_airport, get_airports, get_airports_by_countries, get_airport_details, get_airport_disruptions
• Airlines: get_airlines, get_airline_by_icao, get_airline_logo
• Discovery: search, get_zones, get_most_tracked
• Assets: get_country_flag
• Session: login, logout
• Premium/advanced: get_bookmarks, get_volcanic_eruption_data
• Geometry helpers: get_bounds_by_point, PresetZone

SDK Highlights

• Full FlightTrackerConfig support (faa, satellite, mlat, flarm, adsb, gnd, air, vehicles, estimated, maxage, gliders, stats, limit)
• Countries enum for airport filters
• Advanced options: Pagination, AirportDetailsOptions, HistoryFileType
• Transitional raw endpoints for compatibility
• Strict envelope mapping with InvalidPayload on unknown schemas
• Domain errors: LoginError, AirportNotFound
• Transport hardening: timeout, simple retry backoff, typed Cloudflare 520, cookie store

Technical Details

Typed parsers support multiple known envelope shapes, including direct payloads and nested forms such as result/response and data.

This helps absorb API payload drift without returning loosely typed maps everywhere.

For spherical distance approximation, helper methods use the standard haversine relationship:

$$ d = 2R \arcsin\left(\sqrt{\sin^{2\left(\frac{\Delta\varphi}{2}\right) + \cos(\varphi_1)\cos(\varphi_2)\sin}2\left(\frac{\Delta\lambda}{2}\right)}\right) $$

Where $R$ is Earth radius, $\varphi$ is latitude, and $\lambda$ is longitude.

Roadmap

• Extend airport and flight-details pagination options further
• Replace additional dynamic Value fields with richer typed model fields
• Prepare semver-stable release and publish to crates.io

License

This project is distributed under the MIT License.[^mit]

See LICENSE.

[^mit]: The crate metadata in Cargo.toml is set to MIT.