README

PHP SDK for the Flightradar24 API, built on PSR-18. Bring your own PSR-18 HTTP client and PSR-17 request factory; all API responses are mapped into immutable readonly DTOs.

Requirements

PHP 8.5+
A Flightradar24 API token
Any PSR-18 HTTP client and PSR-17 request factory (e.g. guzzlehttp/guzzle, or symfony/http-client + nyholm/psr7)

Installation

composer require lookyman/flightradar24
# plus an HTTP client + factory, for example:
composer require guzzlehttp/guzzle guzzlehttp/psr7

Authentication

A token is required — there is no environment-variable fallback. Pass it to the Transport constructor. A blank token throws Lookyman\Flightradar24\Exception\MissingApiTokenException.

Usage

use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\Psr7\HttpFactory;
use Lookyman\Flightradar24\Client;
use Lookyman\Flightradar24\Query\Boundary;
use Lookyman\Flightradar24\Query\FlightPositionsQuery;
use Lookyman\Flightradar24\Transport\Transport;

$client = new Client(new Transport($token, new GuzzleClient(), new HttpFactory()));

// Single object:
$airport = $client->airports->getFull('WAW');
echo $airport->name; // "Warsaw Chopin"

// List:
$positions = $client->livePositions->getLight(new FlightPositionsQuery(
    new Boundary(52.5, 52.0, 20.8, 21.3),
));
printf("Found %d aircraft.\n", count($positions));

Every call is synchronous and returns the DTO (or list<Dto>) directly. See examples/basic_usage.php.

Endpoint coverage

Resource method	HTTP request
`livePositions->getLight(FlightPositionsQuery)` → `list<FlightPositionLight>`	`GET /api/live/flight-positions/light`
`livePositions->getFull(FlightPositionsQuery)` → `list<FlightPositionFull>`	`GET /api/live/flight-positions/full`
`livePositions->getCount(FlightPositionsQuery)` → `CountResult`	`GET /api/live/flight-positions/count`
`airports->getLight(string $code)` → `AirportLight`	`GET /api/static/airports/{code}/light`
`airports->getFull(string $code)` → `AirportFull`	`GET /api/static/airports/{code}/full`
`airlines->getLight(string $icao)` → `AirlineLight`	`GET /api/static/airlines/{icao}/light`
`usage->get(UsagePeriod = P24H)` → `list<UsageLogSummary>`	`GET /api/usage`
`historic->positions->getLight/getFull/getCount(HistoricFlightPositionsQuery)`	`GET /api/historic/flight-positions/{light,full,count}`
`historic->events->getLight/getFull(FlightEventsQuery)`	`GET /api/historic/flight-events/{light,full}`
`flightSummary->getLight/getFull/getCount(FlightSummaryQuery)`	`GET /api/flight-summary/{light,full,count}`
`flightTracks->get(string $flightId)` → `list<FlightTracks>`	`GET /api/flight-tracks`

Query value objects

FlightPositionsQuery — all live-position filters (bounds, callsigns, categories, altitudeRanges, gspeed, limit, …); serialises to the API's CSV query format.
Boundary — north, south, west, east; validates latitude/longitude ranges and north > south.
AltitudeRange — minAltitude, maxAltitude.
HistoricFlightPositionsQuery — like FlightPositionsQuery plus a required timestamp (int unix seconds or \DateTimeInterface).
FlightSummaryQuery — flight filters plus flightDatetimeFrom/flightDatetimeTo (string|\DateTimeInterface), sort, limit.
FlightEventsQuery — required flightIds and eventTypes (FlightEventType|string).
Enums: UsagePeriod (24h, 7d, 30d, 1y), FlightCategory (service-type codes), FlightEventType (takeoff, landed, …).

Error handling

Fr24Exception (extends \RuntimeException)
├── MissingApiTokenException   blank API token passed to the Transport constructor
├── TransportException         PSR-18 client failure (network/timeout) or JSON decode error
└── ApiException               non-2xx response
    ├── BadRequestException        400
    ├── AuthenticationException    401
    ├── PaymentRequiredException   402
    ├── NotFoundException          404
    └── RateLimitException         429

Any unmapped 4xx/5xx status surfaces as the base ApiException, which exposes the PSR-7 response:

use Lookyman\Flightradar24\Exception\ApiException;

try {
    $airport = $client->airports->getFull('ZZZ');
} catch (ApiException $e) {
    $status = $e->response->getStatusCode();
    $body = json_decode((string) $e->response->getBody(), true);
}

License

MIT. See LICENSE.

lookyman / flightradar24

Maintainers

Package info

Statistics

Security