# FlightRadarAPI Rust SDK
[](LICENSE)
[](https://docs.rs/flightradarapi)
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
```mermaid
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
```bash
cargo add flightradarapi
```
Run local examples:
```bash
cargo run --example quickstart
cargo run --example airport_lookup
```
## Quickstart
> [!NOTE]
> The example below uses a minimal airline filter and returns typed flight data.
```rust
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
```bash
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
<details>
<summary>Response parsing strategy</summary>
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.
</details>
<details>
<summary>Distance model used by bounds utilities</summary>
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.
</details>
## 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](LICENSE).