Skip to content

Core

See the library quickstart to learn more.

core ¤

FR24 ¤

FR24(
    client: AsyncClient | None = None,
    *,
    base_dir: str = user_cache_dir("fr24")
)

See docs quickstart.

Parameters:

Name Type Description Default
client AsyncClient | None

The httpx client to use. If not provided, a new one will be created with HTTP/2 enabled by default. It is highly recommended to use http2=True to avoid 464 errors and to be consistent with the browser.

 None
base_dir str

See cache directory.

 user_cache_dir('fr24')

login async ¤

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

Parameters:

Name Type Description Default
creds TokenSubscriptionKey | UsernamePassword | None | Literal['from_env']

Reads credentials from the environment variables or the config file if creds is set to "from_env" (default). Otherwise, provide the credentials directly.

 'from_env'

FlightListAPIResp ¤

FlightListAPIResp(ctx: Ctx, response: ApiRspRaw)

Bases: APIResponse[FlightListContext, FlightList]

A wrapper around the flight list API response.

to_arrow ¤

to_arrow() -> FlightListArrow

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

FlightListArrow ¤

FlightListArrow(ctx: Ctx, table: Table)

Bases: ArrowTable[FlightListContext]

A wrapper around a pyarrow.Table containing flight list data.

from_file classmethod ¤

from_file(
    ctx: Ctx, fp: Path, sch_expected: Schema | None = None
) -> Self

Loads data from a parquet file, enforcing the schema if provided.

Raises:

Type Description
RuntimeError

when column names and/or types are unrecognised

concat ¤

concat(
    data_new: FlightListArrow, inplace: bool = False
) -> FlightListArrow

Returns a new list of flights merged with the current table. Duplicates are removed from the current table, which results in all Estimated flights to be updated with the new data (if any).

Parameters:

Name Type Description Default
inplace bool

If True, the current table will be updated in place.

 False

save ¤

save(
    fp: Path | BinaryIO | None = None,
    fmt: Literal["parquet", "csv"] = "parquet",
) -> Self

Write the table to the given file path or file-like object, e.g. ./tmp/foo.parquet, sys.stdout.buffer.

Parameters:

Name Type Description Default
fp Path | BinaryIO | None

File path to save the table to. If None, the table will be saved to the appropriate cache directory.

 None

Raises:

Type Description
ValueError

If a format other than parquet is provided when saving to cache.

FlightListService ¤

FlightListService(http: HTTPClient, base_dir: Path)

Bases: ServiceBase

A service to handle the flight list API and file operations.

fetch async ¤

fetch(
    *,
    reg: str | None = None,
    flight: str | None = None,
    page: int = 1,
    limit: int = 10,
    timestamp: (
        int | datetime | Timestamp | str | None
    ) = "now"
) -> FlightListAPIResp

Fetch one page of flight list for the given registration or flight number.

Related: fr24.json.flight_list

Input either the registration or the flight number, not both.

Parameters:

Name Type Description Default
reg str | None

Aircraft registration (e.g. B-HUJ)

 None
flight str | None

Flight number (e.g. CX8747)

 None
limit int

Number of flights per page - use 100 if authenticated

 10
timestamp int | datetime | Timestamp | str | None

Show flights with ATD before this Unix timestamp

 'now'

fetch_all async ¤

fetch_all(
    *,
    reg: str | None = None,
    flight: str | None = None,
    page: int = 1,
    limit: int = 10,
    timestamp: (
        int | datetime | Timestamp | str | None
    ) = "now",
    delay: int = 5
) -> AsyncIterator[FlightListAPIResp]

Iteratively fetch all pages of the flight list for the given registration or flight number.

Related: fr24.json.flight_list

Input either the registration or the flight number, not both.

Parameters:

Name Type Description Default
reg str | None

Aircraft registration (e.g. B-HUJ)

 None
flight str | None

Flight number (e.g. CX8747)

 None
limit int

Number of flights per page - use 100 if authenticated

 10
timestamp int | datetime | Timestamp | str | None

Show flights with ATD before this Unix timestamp

 'now'
delay int

Delay between requests in seconds

 5

load ¤

load(
    *, reg: str | None = None, flight: str | None = None
) -> FlightListArrow

Get flight list for the given registration or flight number from the cache. If the file does not exist, an empty table will be returned.

Input either the registration or the flight number, not both.

PlaybackAPI ¤

PlaybackAPI(http: HTTPClient)

PlaybackApiResp ¤

PlaybackApiResp(ctx: Ctx, response: ApiRspRaw)

Bases: APIResponse[PlaybackContext, Playback]

A wrapper around the playback API response.

to_arrow ¤

to_arrow() -> PlaybackArrow

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

PlaybackArrow ¤

PlaybackArrow(ctx: Ctx, table: Table)

Bases: ArrowTable[PlaybackContext]

Arrow table for playback data.

metadata property ¤

metadata: FlightData | None

Parse the flight metadata from the arrow table.

from_file classmethod ¤

from_file(
    ctx: Ctx, fp: Path, sch_expected: Schema | None = None
) -> Self

Loads data from a parquet file, enforcing the schema if provided.

Raises:

Type Description
RuntimeError

when column names and/or types are unrecognised

save ¤

save(
    fp: Path | BinaryIO | None = None,
    fmt: Literal["parquet", "csv"] = "parquet",
) -> Self

Write the table to the given file path or file-like object, e.g. ./tmp/foo.parquet, sys.stdout.buffer.

Parameters:

Name Type Description Default
fp Path | BinaryIO | None

File path to save the table to. If None, the table will be saved to the appropriate cache directory.

 None

Raises:

Type Description
ValueError

If a format other than parquet is provided when saving to cache.

PlaybackService ¤

PlaybackService(http: HTTPClient, base_dir: Path)

Bases: ServiceBase

A service to handle the playback API and file operations.

fetch async ¤

fetch(
    flight_id: str | int,
    timestamp: (
        int | datetime | Timestamp | str | None
    ) = None,
) -> PlaybackApiResp

Fetch the historical track playback data for the given flight.

Related: fr24.json.playback

Parameters:

Name Type Description Default
flight_id str | int

Hex Flight ID (e.g. "2d81a27", 0x2d81a27)

 required
timestamp int | datetime | Timestamp | str | None

Unix timestamp (seconds) of ATD - optional, but it is recommended to include it

 None

load ¤

load(flight_id: str | int) -> PlaybackArrow

Get playback data for the given flight ID from the cache. If the file does not exist, an empty table will be returned.

LiveFeedAPIResp ¤

LiveFeedAPIResp(ctx: Ctx, response: ApiRspRaw)

Bases: APIResponse[LiveFeedContext, list[LiveFeedRecord]]

A wrapper around the live feed API response.

to_arrow ¤

to_arrow() -> LiveFeedArrow

Parse each fr24.types.cache.LiveFeedRecord in the API response and transform it into a wrapped pyarrow.Table.

LiveFeedArrow ¤

LiveFeedArrow(ctx: Ctx, table: Table)

Bases: ArrowTable[LiveFeedContext]

Arrow table for live feed data.

from_file classmethod ¤

from_file(
    ctx: Ctx, fp: Path, sch_expected: Schema | None = None
) -> Self

Loads data from a parquet file, enforcing the schema if provided.

Raises:

Type Description
RuntimeError

when column names and/or types are unrecognised

save ¤

save(
    fp: Path | BinaryIO | None = None,
    fmt: Literal["parquet", "csv"] = "parquet",
) -> Self

Write the table to the given file path or file-like object, e.g. ./tmp/foo.parquet, sys.stdout.

Parameters:

Name Type Description Default
fp Path | BinaryIO | None

File path to save the table to. If None, the table will be saved to the appropriate cache directory.

 None

Raises:

Type Description
ValueError

If a format other than parquet is provided when saving to cache.

LiveFeedService ¤

LiveFeedService(http: HTTPClient, base_dir: Path)

Bases: ServiceBase

A service to handle the live feed API and file operations.

fetch async ¤

fetch(
    timestamp: (
        int | str | datetime | Timestamp | None
    ) = None,
    *,
    duration: int | None = None,
    hfreq: int | None = None,
    limit: int = 1500,
    fields: list[LiveFeedField] = [
        "flight",
        "reg",
        "route",
        "type",
    ]
) -> LiveFeedAPIResp

Fetch live feed data.

Related: fr24.grpc.live_feed_world_data

Parameters:

Name Type Description Default
timestamp int | str | datetime | Timestamp | None

Unix timestamp (seconds) of the live feed data. If None, the latest live data will be fetched. Otherwise, historical data will be fetched instead.

 None
duration int | None

Prefetch duration (default: 7 seconds). Should only be set for historical data.

 None
hfreq int | None

High frequency mode (default: 0). Should only be set for historical data.

 None
limit int

Max number of flights (default 1500 for unauthenticated users, 2000 for authenticated users)

 1500
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']

load ¤

load(
    timestamp: int | str | datetime | Timestamp,
) -> LiveFeedArrow

Get live feed data from the cache. If the file does not exist, an empty table will be returned.

Parameters:

Name Type Description Default
timestamp int | str | datetime | Timestamp

Unix timestamp (seconds) of the saved feed snapshot.

 required