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:-
Lazy Loading: Data is fetched only when accessed, minimizing unnecessary network requests. Properties like
session.laps,session.weather, andlap.telemetrytrigger 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, andPolarsDriver, 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_startsetting 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.
session.lapsandlaps_async()run the same parallel fetch. Thelapsproperty runslaps_async()withasyncio.run().- A warm cache serves laps and telemetry from the local SQLite cache instead of the CDN.
- 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 ofsession.car_data): about 260 MB (1.1 million samples)
- The persistent cache and the in-memory LRU tiers use threading locks.
- The lazy
Sessionproperties 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.
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, 1995Merge 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.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.The fastf1 name of
session. Give session or identifier, not both: two different values raise ValueError, and neither raises TypeError.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.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.
"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)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.
"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", 4Enable 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)
TIF1_CACHE_DIR)DataFrame library choice for data representation.
"pandas": Use pandas DataFrames (default, maximum compatibility)"polars": Use polars DataFrames (polarsis a tif1 dependency)None: Use global config value (defaults to"pandas")
tif1. If it has been removed and is requested, tif1 falls back to pandas with a warning.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.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
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.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.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
TheSession 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
Season year (1950 to 2100). Must be within the supported range. Seasons before 2018 have Ergast data only.
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.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.DataFrame library choice. If
None, uses global config value (defaults to "pandas").Properties
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.URL-encoded session name (for example, “Qualifying”, “Practice%201”). For the plain name, read
session.session_name.Grand Prix name as the schedule spells it (for example, “Monaco Grand Prix”). This is
gp without the URL encoding.Session name as the schedule spells it (for example, “Practice 1”, “Race”). This is
session without the URL encoding.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"].DataFrame with one row per driver, in the same order as
drivers. Columns:Driver: 3-letter driver code (for example, “VER”, “HAM”)Team: Team nameDriverNumber: Car number as stringFirstName: Driver’s first nameLastName: Driver’s last nameTeamColor: 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.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.Weather data recorded during the session with columns:
Time: Session time of the sample (timedelta on pandas,Durationon 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)
LapNumber column. To relate weather to laps, use the weather columns on session.laps.Official messages from Race Control with columns:
Time: Message timestamp (datetime)Category: Message category (for example, “Flag”, “SafetyCar”, “Drs”, “Other”)Message: Message textStatus: Status text (for example, “ENABLED”, “DISABLED”, “DEPLOYED”)Flag: Flag type (for example, “GREEN”, “CLEAR”, “DOUBLE YELLOW”, “CHEQUERED”)Scope: Message scopeSector: Affected sector (float)RacingNumber: Affected driver number (string)Lap: Lap number of the message
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) andClassifiedPosition(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
Position. Other sessions are classified from the laps, as fastf1 does:- Practice:
PositionandClassifiedPositionby best lap,Status"Finished",Laps, andTime, the best lap that is not deleted. - Sprint Qualifying and Sprint Shootout (and Qualifying with
ergast=False): the best accurate lap of each segment fillsQ1toQ3. The order is byQ3, thenQ2, thenQ1. A driver out in Q1 outside 107% of the best Q1 time hasClassifiedPosition"N". The knockout applies. A driver out in Q1 has noQ2orQ3time, and a driver out in Q2 has noQ3time. The Q1 cut is 15 of 20 cars or 16 of 22.
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)".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.Ergast pit stops of the race (2011 onward):
DriverNumber, Driver, DriverId, Stop, Lap, TimeOfDay, Duration. Empty for other sessions. Follows the session’s lib.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.Constructors’ championship standings after this event’s round:
Position, PositionText, Points, Wins, TeamId, TeamName, TeamNationality, TeamUrl. Follows the session’s lib.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, andinuse the driver list only. - The keys are the car numbers, also when
drivers.jsonhas none (the 2024 Belgian Grand Prix). tif1 resolves the numbers from Ergast before it builds the keys. The later drivers of a shared car havenumber/Abbreviationkeys, as inresults. - The value is one
Telemetryframe (PolarsTelemetryon polars): every lap of the driver, inSessionTimeorder, with each lap-boundary sample once. It is kept after the first read. Timeis the session clock, as in fastf1: it equalsSessionTime.- The frame holds every telemetry channel: the car channels (
RPM,Speed,nGear,Throttle,Brake,DRS) and the position channels (X,Y,Z).
The same dict as
car_data (fastf1 compatibility): session.pos_data["1"] is the frame that session.car_data["1"] returns.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), andCircuit(Key,ShortName)Key,Type,Name,Path,ArchiveStatus, andSessionStatusStartDateandEndDate: localdatetimevaluesGmtOffset: atimedelta
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.Schedule row for the event (a
pd.Series subclass): RoundNumber, Country, Location, EventName, EventFormat, session names, and dates.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.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.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.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.True when the session has timing and telemetry files (seasons from 2018). Earlier seasons are built from Ergast data.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()
laps: Load lap timing datatelemetry: Prefetch telemetry for all laps (expensive).telemetry=Truealso setslaps=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 oftelemetry=True. Refer to load()weather: Load weather datamessages: Load race control messageslivedata: The fastf1 live-timing recording. tif1 reads historical data only, so any value other thanNoneraisesNotImplementedError
- Self (for method chaining)
load_async()
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
livedatakeyword asload()
- Self (for method chaining)
laps_async()
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
get_driver()
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 (1or"1"), or the full name ("Max Verstappen"). Thenumber/Abbreviationlabel 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 Fagiolidriver: The earlier tif1 name ofidentifier. Give one of the two
- A
Driverobject (aPolarsDriveron a polars session).Driveris aDriverResultsubclass, soisinstance(ver, DriverResult)isTrue.- The values are the
resultsrow of the driver. The 22 fastf1 columns come first (Position,GridPosition,Status,Points,Time, …), then the tif1 extra columns. .dnfisTrueunlessStatusis"Finished","Lapped", or"+N Lap(s)"..nameis theresultslabel of the row ("1","8/fagioli").- In a practice session, tif1 classifies the row from the laps.
Positionis by best lap,Statusis"Finished",Lapscounts the laps, andTimeis the best lap that is not deleted.GridPositionandPointsare NaN. The row is the same whetherresultswas read first or not.
- The values are the
DriverNotFoundError: If the driver does not exist in this session. It is also aValueError, the exception that fastf1 raises for an unknown identifierValueError: If bothidentifieranddriverare given
get_fastest_laps()
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: IfTrue, returns fastest lap per driver. IfFalse, returns single overall fastest lapdrivers: Optional list of driver codes to filter. IfNone, includes all drivers
- A
Lapsframe bound to the session (aPolarsLapson a polars session) with the fastest lap(s). It is the same class whethersession.lapswas read first or not
get_fastest_laps_async()
get_fastest_laps() for parallel data fetching.
get_fastest_lap_tel()
ultra_cold: Enable ultra-low latency mode. IfNone, uses theultra_cold_startconfig value, which applies only to a session that is not in the cache
- DataFrame with telemetry data
get_fastest_lap_tel_async()
get_fastest_lap_tel().
get_fastest_laps_tels()
by_driver: IfTrue, gets fastest lap per driver. IfFalse, gets overall fastestdrivers: Optional list of driver codes to filter
- One telemetry DataFrame for all requested laps. The
Drivercolumn tells the laps apart (it is not a dictionary).
get_fastest_laps_tels_async()
get_fastest_laps_tels().
fetch_driver_laps_parallel()
drivers: List of driver codes
- Dictionary mapping driver codes to lap DataFrames. A driver without data maps to an empty DataFrame
fetch_all_laps_telemetry()
fetch_all_laps_telemetry_async() with asyncio.run().
Parameters:
ultra_cold: Enable ultra-low latency mode (keyword-only). IfNone, uses the config value
- Dictionary mapping
(driver_code, lap_number)tuples to telemetry DataFrames. Missing or failed laps are left out.
drivers filter: filter the dictionary keys instead.
Example:
fetch_all_laps_telemetry_async()
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:
get_circuit_info()
- The
corners.jsonfile 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.
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:
CircuitInfoobject with:corners,marshal_lights,marshal_sectors: DataFrames with columnsX, Y, Number, Letter, Angle, Distancerotation: 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, andsource. Refer to CircuitInfo
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. TheDriver 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
- Later accesses to
driver.lapsreturn the stored frame get_lap(n): O(1) lookup using cached index mapget_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
All laps completed by this driver. Loaded lazily on first access.
Contains all lap timing data including sector times, compounds, stint info, etc.
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 asdriver.driver)driver["TeamName"],driver["TeamColor"]: Team name and hex color codedriver["FirstName"],driver["LastName"],driver["FullName"],driver["HeadshotUrl"]: Identity valuesdriver["Position"],driver["ClassifiedPosition"],driver["GridPosition"],driver["Status"],driver["Points"],driver["Laps"]: The classificationdriver["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
Position, ClassifiedPosition, Status ("Finished"), Laps, and Time (the best lap that is not deleted). GridPosition and Points are NaN.
Methods
get_lap()
lap_number: The lap number to retrieve (1-indexed)
Lapobject for the specified lap
LapNotFoundError: If the lap does not exist for this driverValueError: Iflap_numberis less than 1TypeError: Iflap_numberis not anint(for example, the float19.0)
get_fastest_lap()
Laps DataFrame. Deleted laps are skipped. The result is empty when the driver has no valid lap that was not deleted.
Returns:
- Single-row
LapsDataFrame with the fastest lap data. Use.iloc[0]to read values.
get_fastest_lap_tel()
- DataFrame with telemetry data (Time, Speed, RPM, Throttle, etc.)
Laps
TheLaps 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
Lapsobjects, 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
telemetryproperty 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 matchesDriverNumberonly. 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, sopick_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.
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).
pick_tyre(compound) / pick_compounds(compounds)
Filter laps by tire compound.
"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.
"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 isstatus(default)how="contains": The lap code containsstatushow="excludes": The lap code does not containstatushow="any": The lap code contains at least one character ofstatus("45"matches"4"and"5")how="none": The lap code contains no character ofstatus
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).
get_telemetry(*, frequency=None):Noneuses theTELEMETRY_FREQUENCYclass attribute of the backend’s telemetry class (Telemetryon pandas,PolarsTelemetryon polars), which is"original"by default."original"returns the samples as published. A number resamples to that rate in Hz withresample_channels(). Any other value raisesValueError.get_car_data(**kwargs)/get_pos_data(**kwargs):pad,pad_side, andinterpolate_edgeswork as inTelemetry.slice_by_lap(). Withpad, tif1 slicessession.car_data[driver].
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:
Timeruns from the start of the first lap (SessionTimeminus theLapStartTimeof 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.
Distancerestarts at each lap.add_distance()integrates it again over the whole frame.
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.
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.
Laps objects (Q1, Q2, Q3). A segment without laps is None, as in fastf1. The split uses these sources, in this order:
- The
QualifyingSessioncolumn of the laps, when it has values. session.session_status, with the fastf1 algorithm. EachStartedrow opens a segment, but a restart after anAbortedrow (a red flag) continues the segment. AFinishedrow also ends the suspension. A lap goes to the segment of itsLapStartTime. An out-lap that starts before a split and ends after it goes to the next segment.- Without session status, the two longest gaps of more than 5 minutes between lap start times.
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.
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.
_IterLapResult tuples with:
.index: DataFrame index of the lap.lap:Lapobject (pd.Series) with session reference[column_name]: Direct column access (for example,result["Driver"])
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.
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. TheLap 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
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.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.
Series Data
SinceLap extends pd.Series, lap timing data is accessed via dictionary-style indexing or the get() method:
lap.get('LapTime'): Lap time as timedeltalap.get('LapTimeSeconds'): Lap time in seconds as floatlap.get('LapNumber'): Lap number (same aslap.lap_number)lap.get('Driver'): Driver code (same aslap.driver)lap.get('Sector1Time'),lap.get('Sector2Time'),lap.get('Sector3Time'): Sector times as timedeltaslap.get('Compound'): Tire compoundlap.get('TyreLife'): Tire age in lapslap.get('IsPersonalBest'): Boolean indicating personal best lap
Methods
get_telemetry()
frequency, the samples are the same as in the telemetry property.
Parameters:
frequency:Noneor"original"keeps the published samples. A number resamples to that rate in Hz
TelemetryDataFrame with telemetry samples
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()
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.Seriesnamed after the lap, withTime(the session time of the sample),AirTemp,Humidity,Pressure,Rainfall,TrackTemp,WindDirection, andWindSpeed. A lap without a sample gives the same keys with NaN values, as in fastf1. On a polars session,PolarsLap.get_weather_data()returns adictwith the same keys, withNonevalues 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 lapSpeed: 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 openSource,Status: The constants"merged"and"OnTrack". The edge samples thatinterpolate_edgesadds, and theSourcegaps thatfill_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
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
Troubleshooting
Common Issues
Issue: Driver numbers versus driver codesLapNotFoundError when accessing laps
Related Pages
API Overview
Complete API map
Models
Data structures
Sessions Concept
Understanding sessions
Getting Started
Usage guide