Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TracingInsights/tif1/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Session class represents an F1 session and provides access to all session data including laps, telemetry, weather, and race control messages. It’s the main entry point for loading and working with F1 data.

​
Constructor

Session(year, gp, session, enable_cache=None, lib=None)
​
year
int
required
Season year (2018-current)
​
gp
str | int
required
Grand Prix name or round number (e.g., “Abu Dhabi Grand Prix” or 1)
​
session
str
required
Session name (e.g., “Race”, “Qualifying”, “Practice 1”)
​
enable_cache
bool
default:"None"
Enable caching. If None, uses config value.
​
lib
Literal['pandas', 'polars']
default:"None"
Data library choice. If None, uses config value.

​
Properties

​
laps

session.laps -> DataFrame
Get all laps data for the session. Automatically loads lap data for all drivers in parallel using async requests (4-5x faster than sequential loading). Data is cached globally to avoid redundant loading. Returns: DataFrame with columns:
  • LapNumber, LapTime, Driver, Team
  • Sector1Time, Sector2Time, Sector3Time
  • Compound, TyreLife, Stint
  • Position, TrackStatus, IsPersonalBest

​
drivers

session.drivers -> list[str]
Get list of driver numbers as strings (FastF1 API compatibility). Returns: List of driver numbers as strings (e.g., ['1', '11', '16', ...])

​
drivers_df

session.drivers_df -> pd.DataFrame
Get drivers as a pandas DataFrame. Returns: DataFrame with columns: Driver, Team, DriverNumber, FirstName, LastName, TeamColor, HeadshotUrl

​
weather

session.weather -> DataFrame
Get session weather data. Returns: DataFrame with columns:
  • Time (timedelta): Time offset from session start
  • AirTemp (float): Air temperature in Celsius
  • TrackTemp (float): Track temperature in Celsius
  • Humidity (float): Humidity percentage
  • Pressure (float): Atmospheric pressure
  • WindSpeed (float): Wind speed in km/h
  • WindDirection (int): Wind direction in degrees
  • Rainfall (bool): Whether it’s raining

​
race_control_messages

session.race_control_messages -> DataFrame
Get session race control messages. Returns: DataFrame with columns:
  • Time (datetime): Message timestamp
  • Category (str): Message category
  • Message (str): Message text
  • Status (str): Status
  • Flag (str): Flag type
  • Scope (str): Scope of message
  • Sector (float): Sector number if applicable
  • RacingNumber (str): Driver number if applicable
  • Lap (int): Lap number if applicable

​
results

session.results -> SessionResults
Get session results with driver information. Returns: SessionResults DataFrame with driver positions, points, status, etc.

​
car_data

session.car_data -> DataFrame
Get complete telemetry data for all drivers as a DataFrame. Returns: DataFrame with complete telemetry including:
  • Time/SessionTime: timestamp
  • Driver: driver code
  • Speed: km/h
  • RPM: engine RPM
  • nGear: gear number
  • Throttle: 0-100
  • Brake: boolean or 0-100
  • DRS: DRS status
  • X, Y, Z: position coordinates
  • Distance: distance along track

​
pos_data

session.pos_data -> DataFrame
Alias for car_data - returns the same complete telemetry data.

​
name

session.name -> str
Get session name (decoded from URL encoding). Returns: Session name (e.g., “Practice 1”, “Qualifying”, “Race”)

​
date

session.date -> pd.Timestamp
Get session date. Returns: Session date as pandas Timestamp, or pd.NaT if not available

​
event

session.event -> pd.Series
Get event information for this session. Returns: Event Series with event details

​
session_info

session.session_info -> dict[str, Any]
Get basic session information. Returns: Dictionary with keys: Year, EventName, SessionName

​
Methods

​
load

session.load(laps=True, telemetry=True, weather=True, messages=True) -> Session
Load session data based on requested data types.
​
laps
bool
default:"True"
If True, fetch laps data. Required for telemetry.
​
telemetry
bool
default:"True"
If True, fetch telemetry data for all laps. Automatically sets laps=True.
​
weather
bool
default:"True"
If True, fetch weather data.
​
messages
bool
default:"True"
If True, fetch race control messages.
Returns: self for method chaining Example: 
session = get_session(2025, "Silverstone Grand Prix", "Race")
# Fetch only laps and telemetry
session.load(laps=True, telemetry=True, weather=False, messages=False)
# Fetch everything (default)
session.load()

​
get_driver

session.get_driver(driver) -> Driver
Get driver-specific data.
​
driver
str
required
Driver code (e.g., “VER”, “HAM”)
Returns: Driver object with driver information and laps Raises:
  • TypeError: If driver is not a string
  • ValueError: If driver is empty
  • DriverNotFoundError: If driver not found in session

​
get_fastest_laps

session.get_fastest_laps(by_driver=True, drivers=None) -> DataFrame
Get fastest laps sorted by LapTime. Optimized for cold start - avoids materializing full session laps when possible.
​
by_driver
bool
default:"True"
If True, return fastest lap per driver. If False, return overall fastest.
​
drivers
list[str]
default:"None"
Optional list of driver codes to filter (e.g., [“VER”, “HAM”])
Returns: DataFrame with fastest lap(s) sorted by LapTime with reset index. Returns empty DataFrame if no valid laps found. Example: 
session = get_session(2025, "Monaco Grand Prix", "Race")
# Get fastest lap per driver
fastest = session.get_fastest_laps(by_driver=True)
# Get overall fastest lap
overall = session.get_fastest_laps(by_driver=False)
# Get fastest laps for specific drivers
top3 = session.get_fastest_laps(by_driver=True, drivers=["VER", "HAM", "LEC"])

​
get_circuit_info

session.get_circuit_info() -> CircuitInfo
Return FastF1-compatible circuit info from corners.json. Returns: CircuitInfo instance with:
  • corners: DataFrame with columns X, Y, Number, Letter, Angle, Distance
  • marshal_lights: Empty DataFrame (not in source data)
  • marshal_sectors: Empty DataFrame (not in source data)
  • rotation: Circuit rotation in degrees

​
laps_async

await session.laps_async() -> DataFrame
Get all laps data asynchronously (faster for multiple drivers). Use this when calling from async context. Returns: DataFrame with all laps from all drivers Example: 
import asyncio

async def load_data():
    session = get_session(2025, "Spa Grand Prix", "Race")
    laps = await session.laps_async()
    return laps

laps = asyncio.run(load_data())

​
get_fastest_laps_async

await session.get_fastest_laps_async(by_driver=True, drivers=None) -> DataFrame
Get fastest laps asynchronously.
​
by_driver
bool
default:"True"
If True, return fastest lap per driver. If False, return overall fastest.
​
drivers
list[str]
default:"None"
Optional list of driver codes to filter.
Returns: DataFrame with fastest lap(s) sorted by lap time.

​
fetch_driver_laps_parallel

await session.fetch_driver_laps_parallel(drivers) -> dict[str, DataFrame]
Fetch laps for multiple drivers in parallel using asyncio.gather().
​
drivers
list[str]
required
List of driver codes (e.g., [“VER”, “HAM”, “LEC”])
Returns: Dictionary mapping driver codes to their lap DataFrames. Drivers with no data or errors will have empty DataFrames. Example: 
import asyncio

async def get_top_drivers():
    session = get_session(2025, "Monaco Grand Prix", "Race")
    laps = await session.fetch_driver_laps_parallel(["VER", "HAM", "LEC"])
    return laps

laps_dict = asyncio.run(get_top_drivers())
print(laps_dict["VER"])  # DataFrame with VER's laps

​
Usage Examples

​
Basic Session Loading

import tif1

# Get a session
session = tif1.get_session(2025, "Monaco Grand Prix", "Race")

# Load all data
session.load()

# Access laps
laps = session.laps
print(laps[["Driver", "LapNumber", "LapTime"]].head())

# Access weather
weather = session.weather
print(weather[["Time", "AirTemp", "TrackTemp"]].head())

​
Working with Drivers

# Get specific driver
ver = session.get_driver("VER")
print(ver.laps)

# Get all drivers
for driver_num in session.drivers:
    driver = session.get_driver(driver_num)
    print(f"{driver['Abbreviation']}: {len(driver.laps)} laps")

​
Getting Fastest Laps

# Overall fastest lap
fastest = session.get_fastest_laps(by_driver=False)
print(f"Fastest: {fastest.iloc[0]['Driver']} - {fastest.iloc[0]['LapTime']}")

# Fastest lap per driver
fastest_by_driver = session.get_fastest_laps(by_driver=True)
print(fastest_by_driver[["Driver", "LapTime", "Team"]].head(10))

# Top 3 drivers only
top3 = session.get_fastest_laps(by_driver=True, drivers=["VER", "HAM", "LEC"])

​
Selective Loading

# Load only laps (no telemetry, weather, or messages)
session.load(laps=True, telemetry=False, weather=False, messages=False)

# Load only weather and messages
session.load(laps=False, telemetry=False, weather=True, messages=True)

​
See Also

  • Driver - Driver-specific data access
  • Laps - Collection of lap timing data
  • Telemetry - Telemetry data operations

Build docs developers (and LLMs) love

Get started for freeTalk to us