Services

See the library quickstart to learn more.

fr24

Classes:

Name	Description
FR24

FR24

FR24(client: AsyncClient | None = None)

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

Methods:

Name	Description
login	:param creds: Reads credentials from the environment variables or the

Attributes:

Name	Type	Description
http		The HTTP client for use in requests

http instance-attribute

http = HTTPClient(
    AsyncClient(http2=True) if client is None else client,
    auth=auth,
    grpc_headers=Headers(get_grpc_headers(auth=auth)),
    json_headers=Headers(get_json_headers()),
)

The HTTP client for use in requests

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'

service

Classes:

Name	Description
ServiceFactory
SupportsFetch
APIResult	Wraps the raw Response with request context.
SupportsWriteTable
FlightListService	Flight list service.
FlightListResult	A single result from the flight list API.
FlightListResultCollection	A list of results from the flight list API.
PlaybackService	Playback service.
PlaybackResult
LiveFeedService	Live feed service.
LiveFeedResult
LiveFeedPlaybackService	Live feed service.
LiveFeedPlaybackResult
AirportListService	Airport list service.
AirportListResult
FindService	Find service.
FindResult	A single result from the find API.
NearestFlightsService	Nearest flights service.
NearestFlightsResult
LiveFlightsStatusService	Live flights status service.
LiveFlightsStatusResult
FollowFlightService	Follow flight service for real-time streaming.
FollowFlightResult
TopFlightsService	Top flights service.
TopFlightsResult
FlightDetailsService	Flight details service.
FlightDetailsResult
PlaybackFlightService	Playback flight service.
PlaybackFlightResult

Attributes:

Name	Type	Description
logger
RequestT		Arguments for the request
WriteLocation	TypeAlias

logger module-attribute

logger = getLogger(__name__)

RequestT module-attribute

RequestT = TypeVar('RequestT')

Arguments for the request

WriteLocation module-attribute

WriteLocation: TypeAlias = Union[FileLike, FR24Cache]

ServiceFactory

Methods:

Name	Description
build_flight_list
build_playback
build_live_feed
build_live_feed_playback
build_airport_list
build_find
build_nearest_flights
build_live_flights_status
build_flight_details
build_top_flights
build_follow_flight
build_playback_flight

Attributes:

Name	Type	Description
http	HTTPClient

http instance-attribute

http: HTTPClient

build_flight_list

build_flight_list() -> FlightListService

build_playback

build_playback() -> PlaybackService

build_live_feed

build_live_feed() -> LiveFeedService

build_live_feed_playback

build_live_feed_playback() -> LiveFeedPlaybackService

build_airport_list

build_airport_list() -> AirportListService

build_find

build_find() -> FindService

build_nearest_flights

build_nearest_flights() -> NearestFlightsService

build_live_flights_status

build_live_flights_status() -> LiveFlightsStatusService

build_flight_details

build_flight_details() -> FlightDetailsService

build_top_flights

build_top_flights() -> TopFlightsService

build_follow_flight

build_follow_flight() -> FollowFlightService

build_playback_flight

build_playback_flight() -> PlaybackFlightService

SupportsFetch

Bases: Protocol[RequestT]

Methods:

Name	Description
fetch	Fetches data from the API.

fetch async

fetch(*args: Any, **kwargs: Any) -> APIResult[RequestT]

Fetches data from the API.

APIResult

Bases: Generic[RequestT]

Wraps the raw Response with request context.

Note that at this stage, the response holds the raw bytes, possibly encoded with a scheme. Retrieve the raw bytes with response.content or parse it into json with response.json().

Attributes:

Name	Type	Description
request	RequestT
response	Response

request instance-attribute

request: RequestT

response instance-attribute

response: Response

SupportsWriteTable

Bases: Protocol

Methods:

Name	Description
write_table	Writes the object to the given file path.

write_table

write_table(
    file: WriteLocation,
    *,
    format: TabularFileFmt,
    when_file_exists: FileExistsBehaviour = "backup",
) -> None

Writes the object to the given file path.

FlightListService

Bases: SupportsFetch[FlightListParams]

Flight list service.

Classes:

Name	Description
FetchAllArgs	Arguments for fetching all pages of the flight list.

Methods:

Name	Description
fetch	Fetch the flight list.
fetch_all	Fetch all pages of the flight list.
new_result_collection	Create an empty list of flight list API results.

FetchAllArgs dataclass

FetchAllArgs(
    reg: str | None = None,
    flight: str | None = None,
    page: int = 1,
    limit: int = 10,
    timestamp: IntoTimestamp
    | Literal["now"]
    | None = "now",
    delay: int = 5,
    max_pages: int | None = None,
)

Bases: FlightListParams

Arguments for fetching all pages of the flight list.

Methods:

Name	Description
__post_init__

Attributes:

Name	Type	Description
delay	int	Delay between requests in seconds.
max_pages	int | None	Maximum number of pages to fetch.
reg	str | None	Aircraft registration (e.g. B-HUJ)
flight	str | None	Flight number (e.g. CX8747)
page	int	Page number
limit	int	Number of results per page - use 100 if authenticated.
timestamp	IntoTimestamp | Literal['now'] | None	Show flights with ATD before this Unix timestamp
kind	Literal['reg', 'flight']
ident	str

delay class-attribute instance-attribute

delay: int = field(default=5)

Delay between requests in seconds.

max_pages class-attribute instance-attribute

max_pages: int | None = field(default=None)

Maximum number of pages to fetch.

reg class-attribute instance-attribute

reg: str | None = None

Aircraft registration (e.g. B-HUJ)

flight class-attribute instance-attribute

flight: str | None = None

Flight number (e.g. CX8747)

page class-attribute instance-attribute

page: int = 1

Page number

limit class-attribute instance-attribute

limit: int = 10

Number of results per page - use 100 if authenticated.

timestamp class-attribute instance-attribute

timestamp: IntoTimestamp | Literal['now'] | None = 'now'

Show flights with ATD before this Unix timestamp

kind property

kind: Literal['reg', 'flight']

ident property

ident: str

__post_init__

__post_init__() -> None

fetch async

fetch(
    reg: str | None = None,
    flight: str | None = None,
    page: int = 1,
    limit: int = 10,
    timestamp: IntoTimestamp
    | Literal["now"]
    | None = "now",
) -> FlightListResult

Fetch the flight list.

Parameters:

Name	Type	Description	Default
reg	str | None	Aircraft registration (e.g. B-HUJ)	None
flight	str | None	Flight number (e.g. CX8747)	None
page	int	Page number	1
limit	int	Number of results per page - use 100 if authenticated.	10
timestamp	IntoTimestamp | Literal['now'] | 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: IntoTimestamp
    | Literal["now"]
    | None = "now",
    delay: int = 5,
    max_pages: int | None = None,
) -> AsyncIterator[FlightListResult]

Fetch all pages of the flight list.

Parameters:

Name	Type	Description	Default
reg	str | None	Aircraft registration (e.g. B-HUJ)	None
flight	str | None	Flight number (e.g. CX8747)	None
page	int	Page number	1
limit	int	Number of results per page - use 100 if authenticated.	10
timestamp	IntoTimestamp | Literal['now'] | None	Show flights with ATD before this Unix timestamp	'now'
delay	int	Delay between requests in seconds.	5
max_pages	int | None	Maximum number of pages to fetch.	None

new_result_collection

new_result_collection() -> FlightListResultCollection

Create an empty list of flight list API results.

Methods to_dict and to_polars can be used collect all unique rows in each flight list.

FlightListResult

Bases: APIResult[FlightListParams], SupportsToDict[FlightList], SupportsToPolars, SupportsWriteTable

A single result from the flight list API.

Methods:

Name	Description
to_dict
to_polars
write_table

Attributes:

Name	Type	Description
request	RequestT
response	Response

request instance-attribute

request: RequestT

response instance-attribute

response: Response

to_dict

to_dict() -> FlightList

to_polars

to_polars() -> DataFrame

write_table

write_table(
    file: WriteLocation,
    *,
    format: TabularFileFmt = "parquet",
    when_file_exists: FileExistsBehaviour = "backup",
) -> None

FlightListResultCollection

Bases: list[FlightListResult], SupportsToDict[FlightList], SupportsToPolars, SupportsWriteTable

A list of results from the flight list API.

Methods:

Name	Description
to_dict	Collects the raw bytes in each response into a single result.
to_polars
write_table

to_dict

to_dict() -> FlightList

Collects the raw bytes in each response into a single result. Duplicates are identified by their (flight id, time of departure), and are removed.

No checking is made for the homogenity of the request parameters.

to_polars

to_polars() -> DataFrame

write_table

write_table(
    file: WriteLocation,
    *,
    format: TabularFileFmt = "parquet",
    when_file_exists: FileExistsBehaviour = "backup",
) -> None

PlaybackService

Bases: SupportsFetch[PlaybackParams]

Playback service.

Methods:

Name	Description
fetch	Fetch the playback data for a flight.

fetch async

fetch(
    flight_id: IntoFlightId,
    timestamp: IntoTimestamp | None = None,
) -> PlaybackResult

Fetch the playback data for a flight.

Parameters:

Name	Type	Description	Default
flight_id	IntoFlightId	fr24 flight id, represented in hex	required
timestamp	IntoTimestamp | None	Actual time of departure (ATD) of the historic flight, Unix timestamp in seconds. Optional, but it is recommended to include it.	None

PlaybackResult

Bases: APIResult[PlaybackParams], SupportsToDict[Playback], SupportsToPolars, SupportsWriteTable

Methods:

Name	Description
to_dict
to_polars
metadata	Extracts flight metadata from the response.
write_table

Attributes:

Name	Type	Description
request	RequestT
response	Response

request instance-attribute

request: RequestT

response instance-attribute

response: Response

to_dict

to_dict() -> Playback

to_polars

to_polars() -> DataFrame

metadata

metadata() -> dict[str, Any]

Extracts flight metadata from the response.

write_table

write_table(
    file: WriteLocation,
    *,
    format: TabularFileFmt = "parquet",
    when_file_exists: FileExistsBehaviour = "backup",
) -> None

LiveFeedService

Bases: SupportsFetch[LiveFeedParams]

Live feed service.

Methods:

Name	Description
fetch	Fetch the live feed.

fetch async

fetch(
    bounding_box: BoundingBox,
    stats: bool = False,
    limit: int = 1500,
    maxage: int = 14400,
    fields: set[LiveFeedField] = (
        lambda: {"flight", "reg", "route", "type"}
    )(),
) -> LiveFeedResult

Fetch the live feed.

Parameters:

Name	Type	Description	Default
stats	bool	Whether to include stats in the given area.	False
limit	int	Maximum number of flights (should be set to 1500 for unauthorized users, 2000 for authorized users).	1500
maxage	int	Maximum time since last message update, seconds.	14400
fields	set[LiveFeedField]	Fields to include. For unauthenticated users, a maximum of 4 fields can be included. When authenticated, squawk, vspeed, airspace, logo_id and age can be included.	(lambda: {'flight', 'reg', 'route', 'type'})()

LiveFeedResult

Bases: APIResult[LiveFeedParams], SupportsToProto[LiveFeedResponse], SupportsToDict[dict[str, Any]], SupportsToPolars, SupportsWriteTable

Methods:

Name	Description
to_proto
to_dict
to_polars
write_table

Attributes:

Name	Type	Description
timestamp	IntTimestampS
request	RequestT
response	Response

timestamp instance-attribute

timestamp: IntTimestampS

request instance-attribute

request: RequestT

response instance-attribute

response: Response

to_proto

to_proto() -> LiveFeedResponse

to_dict

to_dict() -> dict[str, Any]

to_polars

to_polars() -> DataFrame

write_table

write_table(
    file: WriteLocation,
    *,
    format: TabularFileFmt = "parquet",
    when_file_exists: FileExistsBehaviour = "backup",
) -> None

LiveFeedPlaybackService

Bases: SupportsFetch[LiveFeedPlaybackParams]

Live feed service.

Methods:

Name	Description
fetch	Fetch a playback of the live feed.

fetch async

fetch(
    bounding_box: BoundingBox,
    stats: bool = False,
    limit: int = 1500,
    maxage: int = 14400,
    fields: set[LiveFeedField] = (
        lambda: {"flight", "reg", "route", "type"}
    )(),
    timestamp: IntoTimestamp | Literal["now"] = "now",
    duration: int = 7,
    hfreq: int | None = None,
) -> LiveFeedPlaybackResult

Fetch a playback of the live feed.

Parameters:

Name	Type	Description	Default
stats	bool	Whether to include stats in the given area.	False
limit	int	Maximum number of flights (should be set to 1500 for unauthorized users, 2000 for authorized users).	1500
maxage	int	Maximum time since last message update, seconds.	14400
fields	set[LiveFeedField]	Fields to include. For unauthenticated users, a maximum of 4 fields can be included. When authenticated, squawk, vspeed, airspace, logo_id and age can be included.	(lambda: {'flight', 'reg', 'route', 'type'})()
timestamp	IntoTimestamp | Literal['now']	Start timestamp	'now'
duration	int	Duration of prefetch, floor(7.5*(multiplier)) seconds For 1x playback, this should be 7 seconds.	7
hfreq	int | None	High frequency mode	None

LiveFeedPlaybackResult

Bases: APIResult[LiveFeedPlaybackParams], SupportsToProto[PlaybackResponse], SupportsToDict[dict[str, Any]], SupportsToPolars, SupportsWriteTable

Methods:

Name	Description
to_proto
to_dict
to_polars
write_table

Attributes:

Name	Type	Description
request	RequestT
response	Response

request instance-attribute

request: RequestT

response instance-attribute

response: Response

to_proto

to_proto() -> PlaybackResponse

to_dict

to_dict() -> dict[str, Any]

to_polars

to_polars() -> DataFrame

write_table

write_table(
    file: WriteLocation,
    *,
    format: TabularFileFmt = "parquet",
    when_file_exists: FileExistsBehaviour = "backup",
) -> None

AirportListService

Bases: SupportsFetch[AirportListParams]

Airport list service.

Methods:

Name	Description
fetch	Fetch the airport list.

fetch async

fetch(
    airport: str,
    mode: Literal["arrivals", "departures", "ground"],
    page: int = 1,
    limit: int = 10,
    timestamp: IntoTimestamp
    | Literal["now"]
    | None = "now",
) -> AirportListResult

Fetch the airport list.

Parameters:

Name	Type	Description	Default
airport	str	IATA airport code (e.g. HKG)	required
mode	Literal['arrivals', 'departures', 'ground']	arrivals, departures or on ground aircraft	required
page	int	Page number	1
limit	int	Number of results per page - use 100 if authenticated.	10
timestamp	IntoTimestamp | Literal['now'] | None	Show flights with STA before this timestamp	'now'

AirportListResult

Bases: APIResult[AirportListParams], SupportsToDict[AirportList]

Methods:

Name	Description
to_dict	Parse the response into a dictionary.

Attributes:

Name	Type	Description
request	RequestT
response	Response

request instance-attribute

request: RequestT

response instance-attribute

response: Response

to_dict

to_dict() -> AirportList

Parse the response into a dictionary.

FindService

Bases: SupportsFetch[FindParams]

Find service.

Methods:

Name	Description
fetch	Fetch the find results.

fetch async

fetch(query: str, limit: int = 50) -> FindResult

Fetch the find results.

Parameters:

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

FindResult

Bases: APIResult[FindParams], SupportsToDict[Find]

A single result from the find API.

Methods:

Name	Description
to_dict	Parse the response into a dictionary.

Attributes:

Name	Type	Description
request	RequestT
response	Response

request instance-attribute

request: RequestT

response instance-attribute

response: Response

to_dict

to_dict() -> Find

Parse the response into a dictionary.

NearestFlightsService

Bases: SupportsFetch[NearestFlightsParams]

Nearest flights service.

Methods:

Name	Description
fetch	Fetch the nearest flights.

fetch async

fetch(
    lat: float,
    lon: float,
    radius: int = 10000,
    limit: int = 1500,
) -> NearestFlightsResult

Fetch the nearest flights.

Parameters:

Name	Type	Description	Default
lat	float	Latitude, degrees, -90 to 90	required
lon	float	Longitude, degrees, -180 to 180	required
radius	int	Radius, metres	10000
limit	int	Maximum number of aircraft to return	1500

NearestFlightsResult

Bases: APIResult[NearestFlightsParams], SupportsToProto[NearestFlightsResponse], SupportsToDict[dict[str, Any]], SupportsToPolars, SupportsWriteTable

Methods:

Name	Description
to_proto
to_dict
to_polars
write_table

Attributes:

Name	Type	Description
timestamp	IntTimestampS
request	RequestT
response	Response

timestamp instance-attribute

timestamp: IntTimestampS

request instance-attribute

request: RequestT

response instance-attribute

response: Response

to_proto

to_proto() -> NearestFlightsResponse

to_dict

to_dict() -> dict[str, Any]

to_polars

to_polars() -> DataFrame

write_table

write_table(
    file: WriteLocation,
    *,
    format: TabularFileFmt = "parquet",
    when_file_exists: FileExistsBehaviour = "backup",
) -> None

LiveFlightsStatusService

Bases: SupportsFetch[LiveFlightsStatusParams]

Live flights status service.

Methods:

Name	Description
fetch	Fetch the live flights status.

fetch async

fetch(
    flight_ids: Sequence[IntoFlightId],
) -> LiveFlightsStatusResult

Fetch the live flights status.

Parameters:

Name	Type	Description	Default
flight_ids	Sequence[IntoFlightId]	List of flight IDs to get status for	required

LiveFlightsStatusResult

Bases: APIResult[LiveFlightsStatusParams], SupportsToProto[LiveFlightsStatusResponse], SupportsToDict[dict[str, Any]], SupportsToPolars, SupportsWriteTable

Methods:

Name	Description
to_proto
to_dict
to_polars
write_table

Attributes:

Name	Type	Description
timestamp	IntTimestampS
request	RequestT
response	Response

timestamp instance-attribute

timestamp: IntTimestampS

request instance-attribute

request: RequestT

response instance-attribute

response: Response

to_proto

to_proto() -> LiveFlightsStatusResponse

to_dict

to_dict() -> dict[str, Any]

to_polars

to_polars() -> DataFrame

write_table

write_table(
    file: WriteLocation,
    *,
    format: TabularFileFmt = "parquet",
    when_file_exists: FileExistsBehaviour = "backup",
) -> None

FollowFlightService

Follow flight service for real-time streaming.

Methods:

Name	Description
stream	Stream real-time flight updates.

stream async

stream(
    flight_id: IntoFlightId,
    restriction_mode: ValueType | str | bytes = NOT_VISIBLE,
) -> AsyncGenerator[FollowFlightResult, None]

Stream real-time flight updates.

Parameters:

Name	Type	Description	Default
flight_id	IntoFlightId	Flight ID to fetch details for. Must be live, or the response will contain an empty DATA frame error.	required
restriction_mode	ValueType | str | bytes	FAA LADD visibility mode.	NOT_VISIBLE

FollowFlightResult

Bases: SupportsToProto[FollowFlightResponse], SupportsToDict[dict[str, Any]]

Methods:

Name	Description
to_proto
to_dict

Attributes:

Name	Type	Description
request	FollowFlightParams
response	bytes

request instance-attribute

request: FollowFlightParams

response instance-attribute

response: bytes

to_proto

to_proto() -> FollowFlightResponse

to_dict

to_dict() -> dict[str, Any]

TopFlightsService

Bases: SupportsFetch[TopFlightsParams]

Top flights service.

Methods:

Name	Description
fetch	Fetch the top flights.

fetch async

fetch(limit: int = 10) -> TopFlightsResult

Fetch the top flights.

Parameters:

Name	Type	Description	Default
limit	int	Maximum number of top flights to return (1-10)	10

TopFlightsResult

Bases: APIResult[TopFlightsParams], SupportsToProto[TopFlightsResponse], SupportsToDict[dict[str, Any]], SupportsToPolars, SupportsWriteTable

Methods:

Name	Description
to_proto
to_dict
to_polars
write_table

Attributes:

Name	Type	Description
timestamp	IntTimestampS
request	RequestT
response	Response

timestamp instance-attribute

timestamp: IntTimestampS

request instance-attribute

request: RequestT

response instance-attribute

response: Response

to_proto

to_proto() -> TopFlightsResponse

to_dict

to_dict() -> dict[str, Any]

to_polars

to_polars() -> DataFrame

write_table

write_table(
    file: WriteLocation,
    *,
    format: TabularFileFmt = "parquet",
    when_file_exists: FileExistsBehaviour = "backup",
) -> None

FlightDetailsService

Bases: SupportsFetch[FlightDetailsParams]

Flight details service.

Methods:

Name	Description
fetch	Fetch flight details.

fetch async

fetch(
    flight_id: IntoFlightId,
    restriction_mode: ValueType | str | bytes = NOT_VISIBLE,
    verbose: bool = True,
) -> FlightDetailsResult

Fetch flight details.

Parameters:

Name	Type	Description	Default
flight_id	IntoFlightId	Flight ID to fetch details for. Must be live, or the response will contain an empty DATA frame error.	required
restriction_mode	ValueType | str | bytes	FAA LADD visibility mode.	NOT_VISIBLE
verbose	bool	Whether to include [fr24.proto.v1_pb2.FlightDetailsResponse.flight_plan] and [fr24.proto.v1_pb2.FlightDetailsResponse.aircraft_details] in the response.	True

FlightDetailsResult

Bases: APIResult[FlightDetailsParams], SupportsToProto[FlightDetailsResponse], SupportsToDict[dict[str, Any]], SupportsToPolars, SupportsWriteTable

Methods:

Name	Description
to_proto
to_dict
to_polars
write_table

Attributes:

Name	Type	Description
timestamp	IntTimestampS
request	RequestT
response	Response

timestamp instance-attribute

timestamp: IntTimestampS

request instance-attribute

request: RequestT

response instance-attribute

response: Response

to_proto

to_proto() -> FlightDetailsResponse

to_dict

to_dict() -> dict[str, Any]

to_polars

to_polars() -> DataFrame

write_table

write_table(
    file: WriteLocation,
    *,
    format: TabularFileFmt = "parquet",
    when_file_exists: FileExistsBehaviour = "backup",
) -> None

PlaybackFlightService

Bases: SupportsFetch[PlaybackFlightParams]

Playback flight service.

Methods:

Name	Description
fetch	Fetch playback flight details.

fetch async

fetch(
    flight_id: IntoFlightId, timestamp: IntoTimestamp
) -> PlaybackFlightResult

Fetch playback flight details.

Parameters:

Name	Type	Description	Default
flight_id	IntoFlightId	Flight ID to fetch details for. Must not be live, or the response will contain an empty DATA frame error.	required
timestamp	IntoTimestamp	Actual time of departure (ATD) of the historic flight	required

PlaybackFlightResult

Bases: APIResult[PlaybackFlightParams], SupportsToProto[PlaybackFlightResponse], SupportsToDict[dict[str, Any]], SupportsToPolars, SupportsWriteTable

Methods:

Name	Description
to_proto
to_dict
to_polars
write_table

Attributes:

Name	Type	Description
request	RequestT
response	Response

request instance-attribute

request: RequestT

response instance-attribute

response: Response

to_proto

to_proto() -> PlaybackFlightResponse

to_dict

to_dict() -> dict[str, Any]

to_polars

to_polars() -> DataFrame

write_table

write_table(
    file: WriteLocation,
    *,
    format: TabularFileFmt = "parquet",
    when_file_exists: FileExistsBehaviour = "backup",
) -> None