Skip to main content
The core module is the center of tif1. It provides the primary interface for loading and working with Formula 1 data. All data access flows through the Session object. The Session object gives access to laps, telemetry, weather, race control messages, and driver information. The API is designed for performance with async support, caching, and lazy loading patterns.

Overview

The core API is built around a hierarchical data model that mirrors the structure of Formula 1 sessions:
Key Design Principles:
  • Lazy Loading: Data is fetched only when accessed, minimizing unnecessary network requests. Properties like session.laps, session.weather, and lap.telemetry trigger data loading on first access.
  • Multi-Layer Caching: Caching strategy with in-memory LRU cache (instant access) and SQLite persistent cache (survives restarts). Cache keys are session-specific and backend-aware (pandas vs polars).
  • Async Support: The main loaders have async variants (laps_async(), get_fastest_laps_tels_async()) that use parallel HTTP requests. The benchmark suite checks that parallel fetching is more than 3x faster than sequential fetching.
  • Backend Flexibility: Choose pandas (default, full compatibility) or polars for DataFrame operations. Backend selection is per-session and affects the lap, telemetry, results, weather, and message frames. On polars, the laps, telemetry, results, and drivers are the polars classes PolarsLaps, PolarsTelemetry, PolarsSessionResults, and PolarsDriver, with the same fastf1 methods.
  • FastF1 Compatibility: Drop-in replacement for FastF1 in common use cases. The common FastF1 methods (pick_driver(), pick_fastest(), iterlaps(), etc.) are supported.
  • Ultra-Cold Mode: On a cold start, this mode skips cache reads, payload validation, and retries. The ultra_cold_start setting is on by default and applies only to sessions that are not in the cache.
  • Error Resilience: Complete exception hierarchy (DataNotFoundError, NetworkError, InvalidDataError) with structured error context. Telemetry failures are counted per driver, and the warnings stop after three failures for a driver.
Performance Characteristics:
  • session.laps and laps_async() run the same parallel fetch. The laps property runs laps_async() with asyncio.run().
  • A warm cache serves laps and telemetry from the local SQLite cache instead of the CDN.
Memory Footprint (2024 Monaco Grand Prix race, 20 drivers, 78 laps):
  • Laps DataFrame (1237 rows): about 0.5 MB
  • Telemetry of one lap: about 115 KB (591 samples)
  • Telemetry of every lap of every driver (fetch_all_laps_telemetry(), or every key of session.car_data): about 260 MB (1.1 million samples)
Thread Safety:
  • The persistent cache and the in-memory LRU tiers use threading locks.
  • The lazy Session properties take no lock. Two threads that read an unloaded property at the same time can both fetch it.

get_session

The main entry point for loading F1 session data. This function handles event name resolution, session validation, and returns a configured Session object ready to load data.
Parameters:
int
required
Season year. Must be within the supported range.Valid range: 1950 to 2100 (the validation range). Timing and telemetry exist from 2018; earlier seasons offer Qualifying and Race sessions built from Ergast data (results, lap times from 1996, pit stops from 2011).Example: 2024, 2025, 1995
bool | None
default:"None"
Merge the official Ergast classification into session.results and order session.drivers by it. None uses the ergast_results setting (on by default). Seasons before 2018 always use Ergast data.
"fastf1" | "f1timing" | "ergast" | None
default:"None"
Schedule backend used to resolve the event name: "fastf1" and "f1timing" read the f1schedule calendar, "ergast" the Ergast race table. None uses f1schedule from 2018 and Ergast before.
bool
default:"False"
Deprecated alias of backend="ergast".
str | int | None
default:"None"
The fastf1 name of session. Give session or identifier, not both: two different values raise ValueError, and neither raises TypeError.
bool
default:"False"
Match gp against the event names only (case-insensitive), as fastf1 does. The alias table and fuzzy matching are skipped, so "Monaco" raises ExactEventNotFoundError (an EventNotFoundError and a KeyError) and "Monaco Grand Prix" resolves.
str | int
required
Grand Prix identifier. Can be specified in multiple ways:
  • Full name: "Monaco Grand Prix", "British Grand Prix"
  • Abbreviated name: "Monaco", "Silverstone", "Spa" (resolved through the alias table, then fuzzy matching)
  • Round number: 6, 12 (1-indexed, based on calendar order). Any number that is not a string is a round number, as in fastf1: a numpy integer or a whole float (8.0) works too.
The function automatically resolves abbreviated names and round numbers to the official event name. A testing event matches only by its exact name ("Pre-Season Testing"); aliases and fuzzy matching never return it. In 2026, the two tests have the names "Pre-Season Testing 1" and "Pre-Season Testing 2", and "Pre-Season Testing" matches the first test.Example: "Monaco Grand Prix", "Monaco", 8 (Monaco was round 8 in 2024)
str | int | None
default:"None"
Session identifier. fastf1 calls this argument identifier, and the identifier= keyword is an alias. Give session or identifier. Can be specified as:
  • Full name: "Practice 1", "Qualifying", "Race"
  • Abbreviated: "FP1", "FP2", "FP3", "Q", "S" (Sprint), "SQ" (Sprint Qualifying), "SS" (Sprint Shootout), "R"
  • Session number: 1 (Practice 1), 2 (Practice 2), 3 (Practice 3), 4 (Qualifying), 5 (Race). A numeric string, a float, or a numpy integer ("5", 5.0) works as in fastf1. In 2021 and 2022, "SQ" and "Sprint Qualifying" mean the Sprint, as in fastf1.
Names and abbreviations are case-insensitive: "race", "Race", "R", and "fp1" all work. Session numbers are 1-indexed and follow the weekend schedule order, so a sprint weekend numbers its sessions differently.Example: "Qualifying", "Q", 4
bool | None
default:"None"
Enable or disable caching for this session.
  • True: Enable caching (recommended for production)
  • False: Disable caching (useful for testing or forcing fresh data)
  • None: Use global config value (default behavior)
Caching behavior: When enabled, all fetched data (laps, telemetry, weather, messages) is stored in a local SQLite database. Subsequent access to the same data reads from cache instead of making network requests.Cache location: tif1’s OS-dependent cache directory (configurable via TIF1_CACHE_DIR)
Literal['pandas', 'polars'] | None
default:"None"
DataFrame library choice for data representation.
  • "pandas": Use pandas DataFrames (default, maximum compatibility)
  • "polars": Use polars DataFrames (polars is a tif1 dependency)
  • None: Use global config value (defaults to "pandas")
Backend note: Polars is installed with tif1. If it has been removed and is requested, tif1 falls back to pandas with a warning.
Returns:
Session
A configured Session object ready to load data. The session is not loaded until its properties are accessed (lazy loading) or session.load() is called explicitly.
Raises:
Exception
Raised in the following cases:
  • Year is outside 1950 to 2100 and the event name is unknown ("Year must be between 1950 and 2100, got 1949"). A round number in such a year raises "Invalid round: 1"
  • Grand Prix round number cannot be resolved ("Invalid round: 30")
  • An event name resembles no event of the season ("No event matching 'Invalid GP' in 2025")
  • A known event name or alias names an event that is not on that season’s calendar ("Suzuka" in 2021)
  • Session name/number does not exist for the specified event
  • Session number is out of range for the event
The unmatched-name case raises FuzzyMatchError, a subclass of EventNotFoundError (a ValueError subclass exported as tif1.EventNotFoundError). It is not a TIF1Error. The calendar case raises the subclass EventNotInSeasonError from tif1.exceptions. It also applies to a known event name in a year outside 1950 to 2100.
Exception
Raised on first data access or load() when no CDN has data for the session. get_session() itself does not fetch session data. For a season without schedule data, an unknown event name is kept as given. Then the error appears only at data access.
Exception
Raised on data access when all CDN sources fail to respond or return errors.
Examples:
Best Practice: Use abbreviated names and session codes for cleaner code:
Event Name Resolution: An exact event name wins first. Next, the per-season alias table resolves circuit, city, and country names: "Silverstone" resolves to "British Grand Prix", and "Spa" resolves to "Belgian Grand Prix". Fuzzy matching handles the rest. A typo such as "Monacco" resolves to the closest event, and tif1 logs a “Correcting user input” warning. A fuzzy match needs a score of at least 70 out of 100. A name that resembles no event, such as "Invalid GP", raises EventNotFoundError.

Session

The Session object is the central hub for all data related to a specific F1 weekend session. It provides access to lap timing data, telemetry, weather conditions, race control messages, driver information, and session results. Design Philosophy:
  • Lazy Loading: Properties are loaded on first access, not at construction time
  • Caching: All fetched data is cached (when enabled) to minimize network requests
  • Locking: The caches use locks for concurrent access; the lazy properties do not
  • Memory Efficient: Only requested data is loaded into memory

Constructor

Direct Construction Not Recommended: Use get_session() instead of constructing Session directly. The get_session() function handles name normalization, validation, and ensures the session exists before creating the object.
Constructor Parameters:
int
required
Season year (1950 to 2100). Must be within the supported range. Seasons before 2018 have Ergast data only.
str | int
required
Grand Prix name or round number (for example, "Monaco Grand Prix", "Monaco", or 8). The constructor resolves it like get_session() does (exact name, alias table, fuzzy matching, round number). Then it URL-encodes the event name.
str
required
Session name as the schedule spells it (for example, "Qualifying", "Race"). The constructor URL-encodes it as given. It does not expand abbreviations such as "Q" or fix the case of "race". It also does not check that the event has the session. get_session() does all three.
bool | None
default:"None"
Enable/disable caching. If None, uses global config value.
Literal['pandas', 'polars'] | None
default:"None"
DataFrame library choice. If None, uses global config value (defaults to "pandas").

Properties

int
The season year (for example, 2025).
str
URL-encoded Grand Prix name (for example, “Monaco%20Grand%20Prix”). Every CDN path and cache key is built from it. For the plain name, read session.event_name.
str
URL-encoded session name (for example, “Qualifying”, “Practice%201”). For the plain name, read session.session_name.
str
Grand Prix name as the schedule spells it (for example, “Monaco Grand Prix”). This is gp without the URL encoding.
str
Session name as the schedule spells it (for example, “Practice 1”, “Race”). This is session without the URL encoding.
Literal['pandas', 'polars']
The DataFrame lib being used for this session.
bool
Whether caching is enabled for this session.
list[str]
List of driver numbers as strings, in classification order (for example, ["81", "63", "4", ...] for the 2025 Bahrain Grand Prix race). session.drivers[:10] is the top ten. Loaded lazily on first access.Some seasons before 2025 list the drivers only by car number. For those, tif1 rebuilds the order from the laps. Races and sprints use laps completed, then the position on the last lap; other sessions use the best lap time. A rebuilt order can miss a post-session penalty.
This returns driver NUMBERS, not driver codes. For driver codes (for example, “VER”, “HAM”), use drivers_df["Driver"].
list[str]
Alias for drivers property. Returns driver numbers as strings.
DataFrame
DataFrame with one row per driver, in the same order as drivers. Columns:
  • Driver: 3-letter driver code (for example, “VER”, “HAM”)
  • Team: Team name
  • DriverNumber: Car number as string
  • FirstName: Driver’s first name
  • LastName: Driver’s last name
  • TeamColor: Hex color code without # (for example, “3671C6”)
  • HeadshotUrl: URL to driver photo
session.results has the same drivers with Abbreviation, TeamName, and FullName columns.Loaded lazily on first access. On a polars session, drivers_df is a plain polars.DataFrame with String columns.
Laps
All laps for all drivers. Includes per-lap weather columns (AirTemp, TrackTemp, Rainfall, …). On pandas, LapTime and the sector times are timedeltas; LapTimeSeconds holds float seconds. With lib="polars", it is a PolarsLaps frame: the time columns are Duration("ns"), LapStartDate is Datetime("ns"), and there is no index column. Loaded lazily on first access. Inside a running event loop, await laps_async() instead.
DataFrame
Weather data recorded during the session with columns:
  • Time: Session time of the sample (timedelta on pandas, Duration on polars)
  • AirTemp: Air temperature (°C)
  • TrackTemp: Track temperature (°C)
  • Humidity: Relative humidity (%)
  • Pressure: Atmospheric pressure (mbar)
  • WindSpeed: Wind speed (m/s)
  • WindDirection: Wind direction (degrees, integer)
  • Rainfall: Rainfall flag (nullable boolean)
The weather frame has no LapNumber column. To relate weather to laps, use the weather columns on session.laps.
DataFrame
Alias for weather property.
DataFrame
Official messages from Race Control with columns:
  • Time: Message timestamp (datetime)
  • Category: Message category (for example, “Flag”, “SafetyCar”, “Drs”, “Other”)
  • Message: Message text
  • Status: Status text (for example, “ENABLED”, “DISABLED”, “DEPLOYED”)
  • Flag: Flag type (for example, “GREEN”, “CLEAR”, “DOUBLE YELLOW”, “CHEQUERED”)
  • Scope: Message scope
  • Sector: Affected sector (float)
  • RacingNumber: Affected driver number (string)
  • Lap: Lap number of the message
SessionResults
The session classification: one row per driver, indexed by driver number, in classification order. On a polars session it is a PolarsSessionResults frame: DriverNumber is a column (polars has no index), and results.row_for("VER") returns the row of one driver. A car two drivers shared (classifications before the 1960s) keeps the plain number for its first driver. The other drivers are labelled number/Abbreviation, so the index is always unique while the DriverNumber column keeps the car number. The columns are fastf1’s, in fastf1’s order, followed by tif1’s extras:
  • DriverNumber, BroadcastName, Abbreviation, DriverId, TeamName, TeamColor, TeamId, FirstName, LastName, FullName, HeadshotUrl, CountryCode (always empty: not in the data)
  • Position (float) and ClassifiedPosition (string, including "R", "D", "W" for retired, disqualified, withdrawn)
  • GridPosition, Q1, Q2, Q3, Time (the total race time), Status, Points, Laps
  • Extras: TimeGap (gap to the winner), FastestLapRank, FastestLapNumber, FastestLapTime, FastestLapAvgSpeed, PermanentNumber, DriverNationality, TeamNationality, DateOfBirth, DriverUrl, TeamUrl
Race, Sprint and Qualifying sessions take these values from the official Ergast classification (grid, points, status, times, qualifying segments). Post-race penalties are therefore included, and drivers that did not start are added with NaN Position. Other sessions are classified from the laps, as fastf1 does:
  • Practice: Position and ClassifiedPosition by best lap, Status "Finished", Laps, and Time, the best lap that is not deleted.
  • Sprint Qualifying and Sprint Shootout (and Qualifying with ergast=False): the best accurate lap of each segment fills Q1 to Q3. The order is by Q3, then Q2, then Q1. A driver out in Q1 outside 107% of the best Q1 time has ClassifiedPosition "N". The knockout applies. A driver out in Q1 has no Q2 or Q3 time, and a driver out in Q2 has no Q3 time. The Q1 cut is 15 of 20 cars or 16 of 22.
These sessions take DriverId and TeamId from the Ergast race results. GridPosition and Points are NaN (polars: null) in every session except races and sprints. With ergast=False (or TIF1_ERGAST_RESULTS=0), no session reads Ergast. Races and sprints are then also classified from the laps, and DriverId, TeamId, GridPosition, Points, and the race Time stay empty. results.iloc[0] is the winner; results.iloc[i].dnf is True unless Status is "Finished", "Lapped" or "+N Lap(s)".
int | None
The scheduled race distance in laps, as in fastf1 (the LapCount live-timing stream, from session_info.json). None for sessions that are not race-like. Without session_info.json, the leader’s lap count of the Ergast classification for Race and Sprint sessions.
DataFrame
Ergast pit stops of the race (2011 onward): DriverNumber, Driver, DriverId, Stop, Lap, TimeOfDay, Duration. Empty for other sessions. Follows the session’s lib.
DataFrame
Drivers’ championship standings after this event’s round: Position, PositionText, Points, Wins, DriverNumber, Abbreviation, DriverId, FirstName, LastName, FullName, DateOfBirth, DriverNationality, TeamIds, TeamNames, DriverUrl. Follows the session’s lib.
DataFrame
Constructors’ championship standings after this event’s round: Position, PositionText, Points, Wins, TeamId, TeamName, TeamNationality, TeamUrl. Follows the session’s lib.
LazyTelemetryDict
The session-long telemetry of each driver, keyed by driver number as in fastf1 (session.car_data["1"]). The abbreviation is also a valid key (session.car_data["VER"]).
  • Nothing is fetched until a key is read. len(), iteration, and in use the driver list only.
  • The keys are the car numbers, also when drivers.json has none (the 2024 Belgian Grand Prix). tif1 resolves the numbers from Ergast before it builds the keys. The later drivers of a shared car have number/Abbreviation keys, as in results.
  • The value is one Telemetry frame (PolarsTelemetry on polars): every lap of the driver, in SessionTime order, with each lap-boundary sample once. It is kept after the first read.
  • Time is the session clock, as in fastf1: it equals SessionTime.
  • The frame holds every telemetry channel: the car channels (RPM, Speed, nGear, Throttle, Brake, DRS) and the position channels (X, Y, Z).
The first read of a key fetches the telemetry of every lap of that driver, which is slow on a cold cache.
LazyTelemetryDict
The same dict as car_data (fastf1 compatibility): session.pos_data["1"] is the frame that session.car_data["1"] returns.
dict
The fastf1 session_info dict: the SessionInfo live-timing payload from session_info.json, with the fastf1 value types.
  • Meeting: Key, Name, OfficialName, Location, Number, Country (Key, Code, Name), and Circuit (Key, ShortName)
  • Key, Type, Name, Path, ArchiveStatus, and SessionStatus
  • StartDate and EndDate: local datetime values
  • GmtOffset: a timedelta
For the 2025 Bahrain Grand Prix race, session_info["Key"] is 10014 and session_info["Meeting"]["Circuit"] is {"Key": 63, "ShortName": "Sakhir"}.Without session_info.json (seasons before 2018), tif1 fills the dict from the schedule row and the packaged circuit table. StartDate and EndDate are then pd.Timestamp values (EndDate is the start plus a nominal duration), GmtOffset is a pd.Timedelta, and Key, Meeting.Key, Path, and ArchiveStatus are None.
str
Session name, same as session_name (for example, “Race”, “Practice 1”).
pd.Timestamp
Session start date and time, in local time at the circuit.
Event
Schedule row for the event (a pd.Series subclass): RoundNumber, Country, Location, EventName, EventFormat, session names, and dates.
pd.Timedelta | datetime.timedelta
The session time of the first Started row of session_status, as in fastf1. For races and sprints, this is the start of the formation lap. On a pandas session it is a pd.Timedelta, NaT when it is not known. On a polars session it is a datetime.timedelta, None when it is not known: polars sessions never import pandas, and their Duration columns return the same type.
pd.Timestamp | datetime.datetime
The wall-clock date (UTC) at session time zero, as in fastf1. On a pandas session it is a pd.Timestamp, NaT for a session without laps (Ergast-only seasons). On a polars session it is a naive datetime.datetime, None for a session without laps.
DataFrame
Session status changes with the columns Time (session time) and Status: the fastf1 SessionStatus live-timing stream. The values are Inactive, Started, Aborted (a red flag), Finished, Finalised, and Ends. In qualifying, each segment has its own Started and Finished rows. Time is timedelta64[ns] on pandas and Duration("ns") on polars.
DataFrame
Track status changes with the columns Time (session time), Status, and Message, with the fastf1 codes and messages:The rows are the fastf1 TrackStatus live-timing stream. The first row is the status when the stream starts, which is not always 1.Time is timedelta64[ns] on pandas and Duration("ns") on polars. laps.pick_track_status() does not read this table: it filters on the TrackStatus codes of the laps.
t0_date, session_start_time, session_status, track_status, session_info, and total_laps come from the session_info.json file of the session (2018 onward). fastf1 reads the same values from live-timing streams that need an F1 account. tif1 fetches the file when one of these attributes is first read (one request of about 2 KB), then reads it from the cache.Without the file, tif1 derives the values from the race control messages, the laps, and the schedule. The derived values are an approximation. The track_status codes come from the flag and safety car messages, and races start at the scheduled time. The derived session_status has no Inactive, Finalised, or Ends rows.
bool
True when the session has timing and telemetry files (seasons from 2018). Earlier seasons are built from Ergast data.
str
The path of the session on the data repositories: "{year}/{gp}/{session}/", with the URL-encoded names (for example, "2025/Bahrain%20Grand%20Prix/Race/").

Methods

load()

Explicitly load session data. By default, data is loaded lazily when accessed. Parameters:
  • laps: Load lap timing data
  • telemetry: Prefetch telemetry for all laps (expensive). telemetry=True also sets laps=True. telemetry="lazy" does not fetch telemetry now. The first access of a lap of a driver fetches all the laps of that driver in one parallel wave. The frames are the same as the frames of telemetry=True. Refer to load()
  • weather: Load weather data
  • messages: Load race control messages
  • livedata: The fastf1 live-timing recording. tif1 reads historical data only, so any value other than None raises NotImplementedError
Returns:
  • Self (for method chaining)
Example:

load_async()

The async twin of load(). It fetches the same tables through the async pipeline only, so it never blocks the event loop. Use it inside a running event loop and in Pyodide, where the synchronous API needs JavaScript Promise Integration. Refer to Pyodide and the Browser. Parameters:
  • The same four flags and the livedata keyword as load()
Returns:
  • Self (for method chaining)
Example:

laps_async()

Asynchronously load all laps for all drivers using parallel HTTP requests. The laps property runs this coroutine with asyncio.run(), so both take the same time. Await it directly when an event loop already runs. Returns:
  • DataFrame with all laps
Example:

get_driver()

Get a driver of the session: the results row of the driver plus the tif1 lap helpers, as the fastf1 get_driver() returns. Parameters:
  • identifier: The 3-letter abbreviation ("VER"), the car number (1 or "1"), or the full name ("Max Verstappen"). The number/Abbreviation label of a shared car also works. Two drivers sometimes shared a car before the 1960s. The car number then gives the first driver of the car, and the label gives the other one. In the 1951 French Grand Prix, "8" is Fangio and "8/fagioli" is Fagioli
  • driver: The earlier tif1 name of identifier. Give one of the two
Returns:
  • A Driver object (a PolarsDriver on a polars session). Driver is a DriverResult subclass, so isinstance(ver, DriverResult) is True.
    • The values are the results row of the driver. The 22 fastf1 columns come first (Position, GridPosition, Status, Points, Time, …), then the tif1 extra columns.
    • .dnf is True unless Status is "Finished", "Lapped", or "+N Lap(s)".
    • .name is the results label of the row ("1", "8/fagioli").
    • In a practice session, tif1 classifies the row from the laps. Position is by best lap, Status is "Finished", Laps counts the laps, and Time is the best lap that is not deleted. GridPosition and Points are NaN. The row is the same whether results was read first or not.
Raises:
  • DriverNotFoundError: If the driver does not exist in this session. It is also a ValueError, the exception that fastf1 raises for an unknown identifier
  • ValueError: If both identifier and driver are given
Example:

get_fastest_laps()

Get the fastest lap(s) from the session. A deleted lap (Deleted == True) is never a fastest lap. A driver whose every timed lap was deleted is left out of the result. This rule differs from Laps.pick_fastest(), which takes the IsPersonalBest laps. Parameters:
  • by_driver: If True, returns fastest lap per driver. If False, returns single overall fastest lap
  • drivers: Optional list of driver codes to filter. If None, includes all drivers
Returns:
  • A Laps frame bound to the session (a PolarsLaps on a polars session) with the fastest lap(s). It is the same class whether session.laps was read first or not
Example:

get_fastest_laps_async()

Async version of get_fastest_laps() for parallel data fetching.

get_fastest_lap_tel()

Get telemetry for the single overall fastest lap of the session. It finds the fastest lap in the raw lap payloads, then fetches only the telemetry file of that lap. Parameters:
  • ultra_cold: Enable ultra-low latency mode. If None, uses the ultra_cold_start config value, which applies only to a session that is not in the cache
Returns:
  • DataFrame with telemetry data
Example:

get_fastest_lap_tel_async()

Async version of get_fastest_lap_tel().

get_fastest_laps_tels()

Parallel fetch telemetry for multiple drivers’ fastest laps. This is faster than fetching telemetry sequentially. Parameters:
  • by_driver: If True, gets fastest lap per driver. If False, gets overall fastest
  • drivers: Optional list of driver codes to filter
Returns:
  • One telemetry DataFrame for all requested laps. The Driver column tells the laps apart (it is not a dictionary).
Example:
Performance Tip: This method fetches telemetry for multiple drivers in parallel. This is faster than calling Driver.get_fastest_lap_tel() for each driver in turn.

get_fastest_laps_tels_async()

Async version of get_fastest_laps_tels().

fetch_driver_laps_parallel()

Fetch lap data for multiple drivers in parallel. Parameters:
  • drivers: List of driver codes
Returns:
  • Dictionary mapping driver codes to lap DataFrames. A driver without data maps to an empty DataFrame
Example:

fetch_all_laps_telemetry()

Fetch telemetry for every lap of every driver. This is a synchronous wrapper that runs fetch_all_laps_telemetry_async() with asyncio.run(). Parameters:
  • ultra_cold: Enable ultra-low latency mode (keyword-only). If None, uses the config value
Returns:
  • Dictionary mapping (driver_code, lap_number) tuples to telemetry DataFrames. Missing or failed laps are left out.
Warning: This can be very slow and data-intensive (about 260 MB for the 2024 Monaco race). Use sparingly. There is no drivers filter: filter the dictionary keys instead. Example:

fetch_all_laps_telemetry_async()

Async version of fetch_all_laps_telemetry(). Fetches telemetry for all laps with parallel HTTP requests. Call it directly when an event loop already runs (for example, in Jupyter). Example:
Memory Warning: The telemetry of a full race can use hundreds of megabytes (260 MB for the 2024 Monaco race). Use this only when all telemetry data is needed. For most use cases, fetch telemetry for specific laps or drivers instead.

get_circuit_info()

Get circuit information: the corners, the marshal lights, the marshal sectors, the track map rotation, and the tif1 extras. Sources:
  • The corners.json file of the session. The new schema carries corner letters, marshal lights and sectors, pit loss, the track outline, track sections, and circuit metadata. The old schema (2021 to 2024 seasons) carries the corners and the rotation only.
  • The MultiViewer API (tif1.mvapi), when the file is missing, invalid, or in the old schema. Corners and rotation from the file always win. MultiViewer fills the marshal frames, the corner letters, and the empty extras. Refer to MultiViewer API.
Seasons before 2018 have no corners.json. MultiViewer knows 32 circuits and has no layout before 2018, so such a session gets the earliest MultiViewer layout of its circuit. A circuit that MultiViewer does not know (for example, the 1995 Pacific Grand Prix at Aida) gets empty frames and an empty source. A failed MultiViewer request is logged at INFO level, and the marshal frames stay empty. This method does not raise for the MultiViewer backup. In offline_mode, it does not ask MultiViewer. Returns:
  • CircuitInfo object with:
    • corners, marshal_lights, marshal_sectors: DataFrames with columns X, Y, Number, Letter, Angle, Distance
    • rotation: Circuit rotation in degrees (float)
    • The tif1 extras: circuit_key, circuit_name, location, country, country_code, country_key, pit_loss, track, sections, mini_sector_index, and source. Refer to CircuitInfo
When a marker has no Distance, tif1 fits it on the fastest lap of the session with the add_marker_distance() method, on pandas and polars sessions. The distances that corners.json gives are kept: fastf1 refits every marker. Seasons before 2018 have no telemetry, so their markers keep a missing Distance. On a polars session, the frames are polars frames. Caching: Results are cached on the session object after the first call. The MultiViewer answer is also kept in the SQLite cache without expiry. Example:
FastF1 Compatibility: CircuitInfo has the attributes of FastF1’s mvapi.CircuitInfo and the tif1 extras. add_marker_distance() uses the same best-fit method: each marker takes the Distance of the nearest XY telemetry sample.

Driver

Represents a specific driver’s performance within a session. Provides convenient access to driver-specific lap data and telemetry. The Driver class extends DriverResult (a pd.Series): its values are the results row of the driver, as in fastf1. Design Philosophy:
  • Lazy Loading: Lap data is loaded on first access to driver.laps
  • Efficient Filtering: When session laps are already loaded, driver laps are filtered from them without additional network requests
  • Prefetching: The get_driver() method can prefetch driver laps in parallel with driver metadata for faster initialization
  • Caching: Lap index maps are cached for O(1) lap number lookups
Performance Characteristics:
  • Later accesses to driver.laps return the stored frame
  • get_lap(n): O(1) lookup using cached index map
  • get_fastest_lap(): O(n) scan of lap times

Constructor

Use session.get_driver() instead of constructing Driver directly. On a polars session, get_driver() returns a PolarsDriver with the same values and methods. Refer to Polars classes.

Properties

str
The 3-letter driver code (for example, “VER”, “HAM”, “LEC”).
DataFrame
All laps completed by this driver. Loaded lazily on first access. Contains all lap timing data including sector times, compounds, stint info, etc.
Session
Reference to the parent session object.
bool
From DriverResult: True when Status is not "Finished", "Lapped", or "+N Lap(s)". An empty status gives False.

Series Data

Driver holds the results row of the driver, so it has the same columns as session.results. Read the values with dictionary-style indexing:
  • driver["DriverNumber"]: Car number as string (for example, “33”, “44”, “16”)
  • driver["Abbreviation"]: 3-letter driver code (same as driver.driver)
  • driver["TeamName"], driver["TeamColor"]: Team name and hex color code
  • driver["FirstName"], driver["LastName"], driver["FullName"], driver["HeadshotUrl"]: Identity values
  • driver["Position"], driver["ClassifiedPosition"], driver["GridPosition"], driver["Status"], driver["Points"], driver["Laps"]: The classification
  • driver["Time"], driver["Q1"], driver["Q2"], driver["Q3"]: The total race time and the qualifying times
  • The tif1 extras: TimeGap, FastestLapRank, FastestLapNumber, FastestLapTime, FastestLapAvgSpeed, PermanentNumber, DriverNationality, TeamNationality, DateOfBirth, DriverUrl, TeamUrl
In a practice session, tif1 builds the row from the laps. It fills Position, ClassifiedPosition, Status ("Finished"), Laps, and Time (the best lap that is not deleted). GridPosition and Points are NaN.

Methods

get_lap()

Get a specific lap by number. Parameters:
  • lap_number: The lap number to retrieve (1-indexed)
Returns:
  • Lap object for the specified lap
Raises:
  • LapNotFoundError: If the lap does not exist for this driver
  • ValueError: If lap_number is less than 1
  • TypeError: If lap_number is not an int (for example, the float 19.0)
Example:

get_fastest_lap()

Get this driver’s fastest lap as a single-row Laps DataFrame. Deleted laps are skipped. The result is empty when the driver has no valid lap that was not deleted. Returns:
  • Single-row Laps DataFrame with the fastest lap data. Use .iloc[0] to read values.
Example:

get_fastest_lap_tel()

Get telemetry for this driver’s fastest lap. Uses the session’s ultra-cold mode setting. Returns:
  • DataFrame with telemetry data (Time, Speed, RPM, Throttle, etc.)
Example:

Laps

The Laps class extends pd.DataFrame and provides a rich set of methods for filtering and analyzing lap timing data. It represents a collection of laps (either for all drivers or a specific driver) with FastF1-compatible filtering methods. Design Philosophy:
  • DataFrame Extension: Inherits all pandas DataFrame methods while adding F1-specific functionality
  • Method Chaining: Most methods return new Laps objects, enabling fluent API patterns
  • FastF1 Compatibility: The pick_* methods use FastF1’s names and arguments. Some options differ, as each method notes
  • Lazy Telemetry: The telemetry property loads telemetry only when accessed

Filtering Methods

pick_driver(identifier) / pick_drivers(identifiers)

Filter laps by driver(s). Accepts driver codes, car numbers (int or string), or Driver objects. The case rules are those of fastf1:
  • pick_drivers() upper-cases the codes, so "ver" matches "VER". A number or a string of digits matches DriverNumber only. It takes one identifier or any iterable: a list, a set, a pandas or polars Series, a numpy array, or a generator.
  • pick_driver() matches the code as given, so pick_driver("ver") returns no laps.

pick_lap(lap_number) / pick_laps(lap_numbers)

Filter by lap number(s). Supports individual numbers, lists, or slices. pick_laps() takes the fastf1 argument name lap_numbers. The earlier tif1 keyword laps= still works. A whole float such as 3.0 is accepted. A fractional one such as 3.5 raises ValueError, as in fastf1.

pick_team(name) / pick_teams(names)

Filter laps by team name(s). The name must match Team exactly, case included, as in fastf1.

pick_fastest(only_by_time=False)

Get the single fastest lap from the collection.
Returns: Single Lap object (pd.Series) or None if no valid laps. By default, pick_fastest() takes the fastest lap among the laps with IsPersonalBest == True, as FastF1 does. A deleted lap is never a personal best. It returns None when no lap is a personal best. pick_fastest(only_by_time=True) returns the lap with the lowest non-null LapTime, of any lap. A frame without an IsPersonalBest column skips the deleted laps instead. In the 2025 Bahrain Grand Prix qualifying, pick_fastest() gives lap 5 of HUL (1:32.067, his Q1 time). His lap 13 (1:31.693) is faster but is not a personal best, so only only_by_time=True returns it. session.get_fastest_laps() and Driver.get_fastest_lap() skip only the deleted laps, so they return lap 13.

pick_quicklaps(threshold=None)

Keep the laps faster than a multiple of the fastest lap time: a lap must be strictly below the threshold, as in fastf1. threshold=None uses Laps.QUICKLAP_THRESHOLD (1.07, so 107% of the fastest lap).
Use Case: Analyzing representative lap times, excluding outliers (slow laps, traffic, mistakes).

pick_tyre(compound) / pick_compounds(compounds)

Filter laps by tire compound.
Common Compounds: "SOFT", "MEDIUM", "HARD", "INTERMEDIATE", "WET". Both methods upper-case the names, as fastf1 does, so "soft" also works. pick_compounds() takes a name or any iterable of names.

pick_track_status(status, how="equals")

Filter laps by track status code.
Track Status Codes:
  • "1": Green flag (normal racing)
  • "2": Yellow flag
  • "4": Safety Car
  • "5": Red flag
  • "6": Virtual Safety Car (VSC)
  • "7": VSC ending
TrackStatus holds every status seen during the lap as one string, so "41" contains Safety Car (4) and green (1). Parameters:
  • how="equals": The lap code is status (default)
  • how="contains": The lap code contains status
  • how="excludes": The lap code does not contain status
  • how="any": The lap code contains at least one character of status ("45" matches "4" and "5")
  • how="none": The lap code contains no character of status
Any other how value raises ValueError, as in fastf1. The filter reads the TrackStatus codes of the laps, never the time-based session.track_status table.

pick_wo_box() / pick_box_laps(which="both")

Filter laps by pit stop activity.

pick_not_deleted() / pick_accurate()

Filter laps by data quality flags.

Data Access Methods

get_telemetry() / get_car_data() / get_pos_data()

Get telemetry data for the laps. For single-driver laps, all three methods return the same merged data (FastF1 compatibility).
Parameters:
  • get_telemetry(*, frequency=None): None uses the TELEMETRY_FREQUENCY class attribute of the backend’s telemetry class (Telemetry on pandas, PolarsTelemetry on polars), which is "original" by default. "original" returns the samples as published. A number resamples to that rate in Hz with resample_channels(). Any other value raises ValueError.
  • get_car_data(**kwargs) / get_pos_data(**kwargs): pad, pad_side, and interpolate_edges work as in Telemetry.slice_by_lap(). With pad, tif1 slices session.car_data[driver].
Returns: A Telemetry DataFrame with 23 columns. The fastf1 columns come first, in the fastf1 order: Date, SessionTime, DriverAhead, DistanceToDriverAhead, Time, RPM, Speed, nGear, and Throttle. Then come Brake, DRS, Source, Distance, RelativeDistance, Status, X, Y, and Z. The tif1 extras AccelerationX/Y/Z, Driver, and LapNumber come last. The telemetry of several laps is one slice, as in fastf1:
  • Time runs from the start of the first lap (SessionTime minus the LapStartTime of that lap). It does not restart at 0 on each lap.
  • The laps of a driver are in session order.
  • Consecutive laps share the sample at their boundary. It appears once.
  • Distance restarts at each lap. add_distance() integrates it again over the whole frame.
A single lap is not changed: its Time starts at 0. Note: get_telemetry() and the telemetry property raise ValueError if the laps contain multiple drivers. get_car_data() and get_pos_data() concatenate the telemetry of every driver instead.

get_weather_data()

Get the weather sample of each lap, as in fastf1.
Returns: One row per lap. The columns are Time (the session time of the sample), AirTemp, Humidity, Pressure, Rainfall, TrackTemp, WindDirection, and WindSpeed, with the dtypes of session.weather_data. The samples come from session.weather_data, with the fastf1 rule. A lap takes the first sample within [LapStartTime, Time], else the last sample before the end of the lap. A lap without a sample gets a row of missing values. The first call loads weather.json if the session has not loaded it. The WeatherTime and weather columns of the laps table are misaligned in the source data. In the 2025 Bahrain race, 435 of the 1,128 laps carry a sample other than the one that the fastf1 rule picks. tif1 reads them only when the session has no weather table. The rows keep the index of the laps. fastf1 indexes them by the weather samples instead. On a polars session, the result is a plain polars.DataFrame without an index.

split_qualifying_sessions()

Split qualifying laps into Q1, Q2, Q3 sessions.
Returns: A list of three Laps objects (Q1, Q2, Q3). A segment without laps is None, as in fastf1. The split uses these sources, in this order:
  1. The QualifyingSession column of the laps, when it has values.
  2. session.session_status, with the fastf1 algorithm. Each Started row opens a segment, but a restart after an Aborted row (a red flag) continues the segment. A Finished row also ends the suspension. A lap goes to the segment of its LapStartTime. An out-lap that starts before a split and ends after it goes to the next segment.
  3. Without session status, the two longest gaps of more than 5 minutes between lap start times.
Raises: ValueError("Session is not a qualifying session!") when the session is not Qualifying, Sprint Qualifying, or Sprint Shootout, as in fastf1.

iterlaps(require=None)

Iterate over laps with optional column requirements. Yields (index, lap) tuples where lap is a Lap object.
Parameters:
  • require: Optional list of column names that must be non-null. Laps with null values in these columns are skipped. The default (None) and an empty list yield every lap, as in fastf1. A column that does not exist yields no laps.
Returns: Generator yielding _IterLapResult tuples with:
  • .index: DataFrame index of the lap
  • .lap: Lap object (pd.Series) with session reference
  • [column_name]: Direct column access (for example, result["Driver"])
Performance: Telemetry is loaded lazily per lap. Each yielded Lap holds every column of the laps, the null ones included, as the fastf1 rows do.

Utility Methods

reset_index(drop=False, **kwargs)

Reset DataFrame index. Automatically removes the level_0 column if pandas creates one. Session laps already have an index column, so pandas puts the old index in level_0. As a result, drop=False also drops the old index.

Properties

telemetry

Get telemetry for all laps in the collection. Only works for single-driver laps.
Returns: Telemetry DataFrame (concatenated telemetry from all laps). Raises: ValueError if laps contain multiple drivers.

Example: Complex Filtering


Lap

Represents a single lap, providing access to high-frequency telemetry data. This is a lightweight wrapper around lap timing data with lazy telemetry loading. The Lap class extends pd.Series, so lap data is accessible as Series data.

Constructor

Use driver.get_lap() instead of constructing Lap directly. Lap takes pd.Series arguments plus the parent session as the session keyword argument.

Properties

float
The lap number (1-indexed). Access via lap.lap_number property. On pandas it is a float (for example, 19.0); wrap it in int() for display or indexing.
str
The 3-letter driver code. Access via lap.driver property.
DataFrame
Telemetry data for this lap. Loaded lazily on first access. Contains Time (relative to the lap start), Speed, RPM, Throttle, Brake, nGear, DRS (0/1), and position data.
Session
Reference to the parent session object.

Series Data

Since Lap extends pd.Series, lap timing data is accessed via dictionary-style indexing or the get() method:
  • lap.get('LapTime'): Lap time as timedelta
  • lap.get('LapTimeSeconds'): Lap time in seconds as float
  • lap.get('LapNumber'): Lap number (same as lap.lap_number)
  • lap.get('Driver'): Driver code (same as lap.driver)
  • lap.get('Sector1Time'), lap.get('Sector2Time'), lap.get('Sector3Time'): Sector times as timedeltas
  • lap.get('Compound'): Tire compound
  • lap.get('TyreLife'): Tire age in laps
  • lap.get('IsPersonalBest'): Boolean indicating personal best lap

Methods

get_telemetry()

Load the telemetry of the lap with the driver-ahead columns, as in fastf1. Without frequency, the samples are the same as in the telemetry property. Parameters:
  • frequency: None or "original" keeps the published samples. A number resamples to that rate in Hz
Returns:
  • Telemetry DataFrame with telemetry samples
Example:

get_car_data()

fastf1-compatible alias of telemetry. With pad, pad_side, and interpolate_edges, it slices the session-long telemetry of the driver (session.car_data[driver]) with Telemetry.slice_by_lap(). Returns:
  • The full telemetry DataFrame of the lap (all 23 columns)

get_pos_data()

fastf1-compatible alias of get_car_data(), with the same keywords. The X, Y, and Z columns hold the position. Returns:
  • The full telemetry DataFrame of the lap (all 23 columns)

get_weather_data()

The weather sample of the lap from session.weather_data, with the fastf1 rule. The lap takes the first sample within [LapStartTime, Time], else the last one before the lap ended. The WeatherTime columns of the laps table are used only when the session has no weather table. Returns:
  • A pd.Series named after the lap, with Time (the session time of the sample), AirTemp, Humidity, Pressure, Rainfall, TrackTemp, WindDirection, and WindSpeed. A lap without a sample gives the same keys with NaN values, as in fastf1. On a polars session, PolarsLap.get_weather_data() returns a dict with the same keys, with None values when the lap has no sample

Complete Examples

Basic session usage

Working with Drivers

Working with Telemetry

Available Telemetry Columns:
  • Date: Wall-clock time of the sample (datetime64[ns] on pandas, Datetime("ns") on polars)
  • SessionTime: Session time of the sample (timedelta64[ns] on pandas, Duration("ns") on polars)
  • Time: Time since the lap start (timedelta64[ns] on pandas, Duration("ns") on polars). The telemetry of several laps counts from the start of the first lap
  • Speed: Speed in km/h (float)
  • RPM: Engine RPM (float)
  • Throttle: Throttle position (0-100%, float)
  • Brake: Brake applied (boolean on both backends)
  • nGear: Gear number (Int64)
  • DRS: DRS flag (0 = closed, 1 = open, Int64). fastf1 keeps the raw codes 10, 12, and 14 for open
  • Source, Status: The constants "merged" and "OnTrack". The edge samples that interpolate_edges adds, and the Source gaps that fill_missing() fills, hold "interpolation"
  • X, Y, Z: 3D position coordinates (1/10 m)
  • Distance, RelativeDistance: Distance along the lap (meters, and 0-1 fraction)
  • DriverAhead, DistanceToDriverAhead: Car number of the car ahead and the gap in meters (missing when no car is ahead)
  • AccelerationX, AccelerationY, AccelerationZ: Acceleration channels (m/s²)
  • Driver, LapNumber: Lap identity

Parallel data loading

Performance Tip: The laps property and laps_async() both fetch all driver lap data in parallel. Use the async methods when an event loop already runs, or to overlap several loads.

Ultra-cold start mode

Ultra-cold mode skips cache reads, payload validation, and retries on the critical path for faster cold starts. Use it when minimal latency is needed and not all session data is required. The trade-off is that payload validation is skipped.

Error Handling

Best Practices:
  • Use async methods (laps_async(), get_fastest_laps_tels_async()) inside a running event loop
  • Enable caching to speed up subsequent loads
  • Use ultra_cold=True when only specific data is needed
  • Filter drivers with the drivers parameter to reduce data transfer

Troubleshooting

Common Issues

Issue: Driver numbers versus driver codes
Issue: LapNotFoundError when accessing laps
Issue: Empty telemetry data
Issue: Slow data loading

API Overview

Complete API map

Models

Data structures

Sessions Concept

Understanding sessions

Getting Started

Usage guide
Last modified on November 3, 2026