See the example gallery to learn more.

authentication

get_credentials

get_credentials() -> (
    TokenSubscriptionKey | UsernamePassword | None
)

Reads credentials from the environment variables, overriding it with the config file if it exists.

login async

login(
    client: AsyncClient,
    creds: (
        TokenSubscriptionKey
        | UsernamePassword
        | None
        | Literal["from_env"]
    ) = "from_env",
) -> None | Authentication

Read credentials and logs into the API.

By default, credentials are read from the environment variables or the config file if creds_override is not set. Then, if the credentials: - username and password is set: makes a POST request to the login endpoint - subscription_key and token is set: returns immediately - otherwise, None is returned

login_with_username_password async

login_with_username_password(
    client: AsyncClient, username: str, password: str
) -> Authentication

Retrieve bearer token and subscription key from the API.

Bearer: json['userData']['accessToken'] token= query param: json['userData']['subscriptionKey']

login_with_token_subscription_key async

login_with_token_subscription_key(
    _client: AsyncClient,
    subscription_key: str,
    token: str | None,
) -> Authentication | None

Login with subscription key and/or token. Falls back to anonymous access if token is expired or invalid.

JSON endpoints

json

flight_list async

flight_list(
    client: AsyncClient,
    reg: None | str = None,
    flight: None | str = None,
    page: int = 1,
    limit: int = 10,
    timestamp: (
        int | datetime | Timestamp | str | None
    ) = "now",
    auth: None | Authentication = None,
) -> FlightList

Fetch metadata/history of flights for a given aircraft or flight number.

Includes basic information such as status, O/D, scheduled/estimated/real times: see fr24.types.flight_list.FlightList for more details.

Use either reg or flight to query. To determine if there are more pages to query, check the response .result.response.page.more.

Parameters:

Name	Type	Description	Default
client	AsyncClient	HTTPX async client	required
reg	None | str	Aircraft registration (e.g. B-HUJ)	None
flight	None | str	Flight number (e.g. CX8747)	None
page	int	Page number	1
limit	int	Number of results per page - use 100 if authenticated.	10
timestamp	int | datetime | Timestamp | str | None	Show flights with ATD before this Unix timestamp	'now'
auth	None | Authentication	Authentication data	None

airport_list async

airport_list(
    client: AsyncClient,
    airport: str,
    mode: (
        Literal["arrivals"]
        | Literal["departures"]
        | Literal["ground"]
    ),
    page: int = 1,
    limit: int = 10,
    timestamp: (
        int | datetime | Timestamp | str | None
    ) = "now",
    auth: None | Authentication = None,
) -> AirportList

Fetch aircraft arriving, departing or on ground at a given airport.

Returns on ground/scheduled/estimated/real times: see fr24.types.flight_list.FlightListItem for more details.

Parameters:

Name	Type	Description	Default
client	AsyncClient	HTTPX async client	required
airport	str	IATA airport code (e.g. HKG)	required
mode	Literal['arrivals'] | Literal['departures'] | Literal['ground']	arrivals, departures or on ground aircraft	required
page	int	Page number	1
limit	int	Number of results per page (max 100)	10
timestamp	int | datetime | Timestamp | str | None	Show flights with STA before this Unix timestamp	'now'
auth	None | Authentication	Authentication data	None

playback async

playback(
    client: AsyncClient,
    flight_id: int | str,
    timestamp: (
        int | str | datetime | Timestamp | None
    ) = None,
    auth: None | Authentication = None,
) -> Playback

Fetch historical track playback data for a given flight.

Parameters:

Name	Type	Description	Default
client	AsyncClient	HTTPX async client	required
flight_id	int | str	fr24 hex flight id	required
timestamp	int | str | datetime | Timestamp | None	Unix timestamp (seconds) of ATD - optional, but it is recommended to include it	None
auth	None | Authentication	Authentication data	None

find async

find(client: AsyncClient, query: str) -> FindResult | None

General search.

Parameters:

Name	Type	Description	Default
query	str	Airport, schedule (HKG-CDG), or aircraft.	required

playback_metadata_dict

playback_metadata_dict(flight: FlightData) -> dict

Flatten and rename important variables in the flight metadata to a dictionary.

playback_track_dict

playback_track_dict(
    point: TrackData,
) -> PlaybackTrackRecord

Flatten and rename each variable in this observation into a new dictionary.

Note

The JSON response claims that heading is available, but ADS-B only transmits the ground track. Heading is only available in EMS data.

We rename it to track to avoid confusion.

playback_track_ems_dict

playback_track_ems_dict(
    point: TrackData,
) -> PlaybackTrackEMSRecord | None

If the Enhanced Mode-S data is available in this observation, flatten and rename each variable to a dictionary. Otherwise, return None.

playback_arrow

playback_arrow(data: Playback) -> Table

Parse each fr24.types.playback.TrackData in the API response into a pyarrow.Table. Also adds fr24.types.playback.FlightData into the schema's metadata with key _flight.

If the response is empty, a warning is logged and an empty table is returned

playback_df

playback_df(data: Playback) -> DataFrame

Parse each fr24.types.playback.TrackData in the API response into a pandas DataFrame. Also adds fr24.types.playback.FlightData into the DataFrame's .attrs.

If the response is empty, a warning is logged and an empty table is returned

flight_list_dict

flight_list_dict(entry: FlightListItem) -> FlightListRecord

Flatten a flight entry into dict, converting fr24 hex ids into integers.

flight_list_arrow

flight_list_arrow(data: FlightList) -> Table

Parse each fr24.types.flight_list.FlightListItem in the API response into a pyarrow.Table.

If the response is empty, a warning is logged and an empty table is returned

flight_list_df

flight_list_df(data: FlightList) -> DataFrame

Parse each fr24.types.flight_list.FlightListItem in the API response into a pandas DataFrame.

If the response is empty, a warning is logged and an empty table is returned

gRPC endpoints

grpc

Endpoint: https://data-feed.flightradar24.com

Service name: fr24.feed.api.v1.Feed

Methods:

• LiveFeed
• Playback
• NearestFlights
• LiveFlightsStatus
• FollowFlight
• TopFlights
• LiveTrail

world_zones module-attribute

world_zones = [
    (90, -90, lng_bounds[i], lng_bounds[i + 1])
    for i in range(len(lng_bounds) - 1)
]

construct_request

construct_request(
    method_name: str,
    message: T,
    auth: None | Authentication = None,
) -> Request

Construct the gRPC request with encoded gRPC body.

post_unary async

post_unary(
    client: AsyncClient,
    request: Request,
    msg_type: Type[T],
) -> T

Execute the unary-unary call and return the parsed protobuf message.

post_stream async

post_stream(
    client: AsyncClient,
    request: Request,
    msg_type: Type[T],
) -> AsyncIterator[T]

Execute the unary-stream call and yield each parsed protobuf message.

live_feed_message_create

live_feed_message_create(
    north: float = 50,
    south: float = 40,
    west: float = 0,
    east: float = 10,
    stats: bool = False,
    limit: int = 1500,
    maxage: int = 14400,
    fields: list[LiveFeedField] = [
        "flight",
        "reg",
        "route",
        "type",
    ],
    **kwargs: Any
) -> LiveFeedRequest

Create the LiveFeedRequest protobuf message

Parameters:

Name	Type	Description	Default
north	float	North latitude (degrees)	50
south	float	South latitude (degrees)	40
west	float	West longitude (degrees)	0
east	float	East longitude (degrees)	10
stats	bool	Include stats of the given area	False
limit	int	Max number of flights (default 1500 for unauthenticated users, 2000 for authenticated users)	1500
maxage	int	Max age since last update, seconds	14400
fields	list[LiveFeedField]	fields to include - for unauthenticated users, max 4 fields. When authenticated, squawk, vspeed, airspace, logo_id and age can be included	['flight', 'reg', 'route', 'type']

live_feed_request_create

live_feed_request_create(
    message: LiveFeedRequest,
    auth: None | Authentication = None,
) -> Request

live_feed_post async

live_feed_post(
    client: AsyncClient, request: Request
) -> LiveFeedResponse

live_feed_playback_message_create

live_feed_playback_message_create(
    message: LiveFeedRequest,
    timestamp: int,
    prefetch: int,
    hfreq: int,
) -> PlaybackRequest

Create the live feed playback request protobuf message.

Parameters:

Name	Type	Description	Default
timestamp	int	Start timestamp	required
prefetch	int	End timestamp: should be start timestamp + 7 seconds	required
hfreq	int	High frequency mode	required

live_feed_playback_request_create

live_feed_playback_request_create(
    message: PlaybackRequest,
    auth: None | Authentication = None,
) -> Request

live_feed_playback_post async

live_feed_playback_post(
    client: AsyncClient, request: Request
) -> PlaybackResponse

live_feed_flightdata_dict

live_feed_flightdata_dict(lfr: Flight) -> LiveFeedRecord

Convert the protobuf message to a dictionary.

live_feed_world_data async

live_feed_world_data(
    client: AsyncClient,
    auth: None | Authentication = None,
    limit: int = 1500,
    fields: list[LiveFeedField] = [
        "flight",
        "reg",
        "route",
        "type",
    ],
) -> list[LiveFeedRecord]

Retrieve live feed data for the entire world, in chunks.

live_feed_playback_world_data async

live_feed_playback_world_data(
    client: AsyncClient,
    timestamp: int,
    duration: int = 7,
    hfreq: int = 0,
    auth: None | Authentication = None,
    limit: int = 1500,
    fields: list[LiveFeedField] = [
        "flight",
        "reg",
        "route",
        "type",
    ],
) -> list[LiveFeedRecord]

Retrieve live feed playback data for the entire world, in chunks.

Raises:

Type	Description
RuntimeError	if more than half of the requests fail

nearest_flights_request_create

nearest_flights_request_create(
    message: NearestFlightsRequest,
    auth: None | Authentication = None,
) -> Request

nearest_flights_post async

nearest_flights_post(
    client: AsyncClient, request: Request
) -> NearestFlightsResponse

live_flights_status_request_create

live_flights_status_request_create(
    message: LiveFlightsStatusRequest,
    auth: None | Authentication = None,
) -> Request

live_flights_status_post async

live_flights_status_post(
    client: AsyncClient, request: Request
) -> LiveFlightsStatusResponse

follow_flight_request_create

follow_flight_request_create(
    message: FollowFlightRequest,
    auth: None | Authentication = None,
) -> Request

follow_flight_stream async

follow_flight_stream(
    client: AsyncClient, request: Request
) -> AsyncIterator[FollowFlightResponse]

top_flights_request_create

top_flights_request_create(
    message: TopFlightsRequest,
    auth: None | Authentication = None,
) -> Request

top_flights_post async

top_flights_post(
    client: AsyncClient, request: Request
) -> TopFlightsResponse

live_trail_request_create

live_trail_request_create(
    message: LiveTrailRequest,
    auth: None | Authentication = None,
) -> Request

live_trail_post async

live_trail_post(
    client: AsyncClient, request: Request
) -> LiveTrailResponse