Functions

See the example gallery to learn more.

livefeed

livefeed_message_create

livefeed_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	50
south	float	South latitude	40
west	float	West longitude	0
east	float	East longitude	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']

livefeed_playback_message_create

livefeed_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

livefeed_request_create

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

Construct the POST request with encoded gRPC body.

livefeed_playback_request_create

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

Constructs the POST request with encoded gRPC body.

livefeed_post async

livefeed_post(
    client: AsyncClient, request: Request
) -> bytes

Send the request and extract the raw protobuf message.

livefeed_response_parse

livefeed_response_parse(data: bytes) -> LiveFeedResponse

Parameters:

Name	Type	Description	Default
data	bytes	raw protobuf message	required

livefeed_playback_response_parse

livefeed_playback_response_parse(
    data: bytes,
) -> LiveFeedResponse

Parameters:

Name	Type	Description	Default
data	bytes	raw protobuf message	required

livefeed_flightdata_dict

livefeed_flightdata_dict(lfr: Flight) -> LiveFeedRecord

Convert the protobuf message to a dictionary.

livefeed_world_data async

livefeed_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.

livefeed_playback_world_data async

livefeed_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
Exception	if more than half of the requests fail

history

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.fr24.FlightData 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.fr24.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

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.fr24.TrackData in the API response into a pyarrow.Table. Also adds fr24.types.fr24.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.fr24.TrackData in the API response into a pandas DataFrame. Also adds fr24.types.fr24.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.fr24.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.fr24.FlightListItem in the API response into a pandas DataFrame.

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

find

find async

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

General search.

Parameters:

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

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.