Core API

Session (2024 Monaco Grand Prix - Race)
├── Laps (all drivers, all laps)
├── Drivers (VER, HAM, LEC, ...)
│   └── Driver (VER)
│       ├── Laps (VER's laps only)
│       └── Lap (VER lap 19)
│           └── Telemetry (high-frequency data)
├── Weather (temperature, humidity, wind)
├── RaceControlMessages (flags, safety car)
├── Results (final classification)
└── CircuitInfo (corners, track layout)

def get_session(
    year: int,
    gp: str | int,
    session: str | int,
    enable_cache: bool | None = None,
    lib: Literal["pandas", "polars"] | None = None
) -> Session

Session(
    year: int,
    gp: str,
    session: str,
    enable_cache: bool | None = None,
    lib: Literal["pandas", "polars"] | None = None
)

def load(
    laps: bool = True,
    telemetry: bool = True,
    weather: bool = True,
    messages: bool = True
) -> Session

# Load only laps and weather
session = tif1.get_session(2021, "Belgian Grand Prix", "Race")
session.load(laps=True, telemetry=False, weather=True, messages=False)

# Or use lazy loading (recommended)
session = tif1.get_session(2021, "Belgian Grand Prix", "Race")
laps = session.laps  # Loads automatically

async def laps_async() -> DataFrame

import asyncio
import tif1

async def main():
    session = tif1.get_session(2021, "Belgian Grand Prix", "Race")
    laps = await session.laps_async()
    print(f"Loaded {len(laps)} laps")

asyncio.run(main())

def get_driver(driver: str | int) -> Driver

ver = session.get_driver("VER")
ver = session.get_driver(33)  # By number

def get_fastest_laps(
    by_driver: bool = True,
    drivers: list[str] | None = None
) -> DataFrame

# Fastest lap per driver
fastest = session.get_fastest_laps(by_driver=True)

# Overall fastest lap
fastest = session.get_fastest_laps(by_driver=False)

# Fastest laps for specific drivers
fastest = session.get_fastest_laps(by_driver=True, drivers=["VER", "HAM", "BOT"])

async def get_fastest_laps_async(
    by_driver: bool = True,
    drivers: list[str] | None = None
) -> DataFrame

def get_fastest_lap_tel(ultra_cold: bool | None = None) -> DataFrame

# Get fastest lap telemetry
tel = session.get_fastest_lap_tel()
print(f"Max speed: {tel['Speed'].max()} km/h")

async def get_fastest_lap_tel_async(
    ultra_cold: bool | None = None
) -> DataFrame

def get_fastest_laps_tels(
    by_driver: bool = True,
    drivers: list[str] | None = None,
    ultra_cold: bool | None = None
) -> dict[str, DataFrame]

# Get telemetry for all drivers' fastest laps
tels = session.get_fastest_laps_tels(by_driver=True)

for driver, tel in tels.items():
    print(f"{driver}: {tel['Speed'].max():.1f} km/h")

# Get telemetry for specific drivers
tels = session.get_fastest_laps_tels(
    by_driver=True,
    drivers=["VER", "HAM", "BOT"]
)

async def get_fastest_laps_tels_async(
    by_driver: bool = True,
    drivers: list[str] | None = None,
    ultra_cold: bool | None = None
) -> dict[str, DataFrame]

async def fetch_driver_laps_parallel(
    drivers: list[str]
) -> dict[str, DataFrame]

import asyncio

async def main():
    session = tif1.get_session(2021, "Belgian Grand Prix", "Race")
    laps_dict = await session.fetch_driver_laps_parallel(["VER", "HAM", "BOT"])

    for driver, laps in laps_dict.items():
        print(f"{driver}: {len(laps)} laps")

asyncio.run(main())

def fetch_all_laps_telemetry(
    drivers: list[str] | None = None,
    ultra_cold: bool | None = None
) -> dict[tuple[str, int], DataFrame]

# Fetch all telemetry for specific drivers (slow!)
all_tels = session.fetch_all_laps_telemetry(drivers=["VER", "HAM"])

for (driver, lap_num), tel in all_tels.items():
    print(f"{driver} Lap {lap_num}: {len(tel)} samples")

async def fetch_all_laps_telemetry_async(
    drivers: list[str] | None = None,
    ultra_cold: bool | None = None
) -> dict[tuple[str, int], DataFrame]

import asyncio
import tif1

async def main():
    session = tif1.get_session(2024, "Monaco", "Race")
    # Fetch telemetry for all laps of specific drivers
    all_tels = await session.fetch_all_laps_telemetry_async(
        drivers=["VER", "HAM"]
    )

    for (driver, lap_num), tel in all_tels.items():
        print(f"{driver} Lap {lap_num}: {len(tel)} samples, "
              f"max speed: {tel['Speed'].max():.1f} km/h")

asyncio.run(main())

def get_circuit_info() -> CircuitInfo

circuit = session.get_circuit_info()

# Access corner data
print(f"Number of corners: {len(circuit.corners)}")
print(circuit.corners[["Number", "X", "Y", "Distance"]].head())

# Add distance markers to corners using a reference lap
ver = session.get_driver("VER")
fastest_lap = ver.get_lap(19)
circuit.add_marker_distance(fastest_lap)

# Now corners have accurate distance values
print(circuit.corners[["Number", "Distance"]].head())

Driver(
    session: Session,
    driver: str,
    prefetched_lap_data: dict[str, Any] | None = None
)

def get_lap(lap_number: int) -> Lap

ver = session.get_driver("VER")
lap_19 = ver.get_lap(19)
print(f"Lap time: {lap_19.lap_time:.3f}s")

def get_fastest_lap() -> DataFrame

fastest = ver.get_fastest_lap()
print(f"Fastest: {fastest['LapTime'].iloc[0]:.3f}s")
print(f"Compound: {fastest['Compound'].iloc[0]}")

def get_fastest_lap_tel() -> DataFrame

fastest_tel = ver.get_fastest_lap_tel()
print(f"Max speed: {fastest_tel['Speed'].max():.1f} km/h")
print(f"Avg throttle: {fastest_tel['Throttle'].mean():.1f}%")

# Single driver
ver_laps = laps.pick_driver("VER")
ver_laps = laps.pick_driver(33)  # By number

# Multiple drivers
top_3_laps = laps.pick_drivers(["VER", "HAM", "LEC"])

# Single lap
lap_1 = laps.pick_lap(1)

# Multiple laps
first_10 = laps.pick_laps(range(1, 11))

# Slice notation
first_10 = laps.pick_laps(slice(1, 10))
middle_laps = laps.pick_laps(slice(10, 50))
from_lap_20 = laps.pick_laps(slice(20, None))  # Lap 20 onwards

# Single team
rb_laps = laps.pick_team("Red Bull Racing")

# Multiple teams
top_teams = laps.pick_teams(["Red Bull Racing", "Mercedes", "Ferrari"])

# Get fastest lap
fastest = laps.pick_fastest()
print(f"Fastest: {fastest['Driver']} - {fastest['LapTimeSeconds']:.3f}s")

# Returns None if no valid laps
if fastest is not None:
    print(f"Compound: {fastest['Compound']}")

# Get all laps within 107% of fastest
quick_laps = laps.pick_quicklaps()

# Stricter threshold (within 103%)
very_quick = laps.pick_quicklaps(threshold=1.03)

# More lenient (within 110%)
decent_laps = laps.pick_quicklaps(threshold=1.10)

# Single compound
soft_laps = laps.pick_tyre("SOFT")

# Multiple compounds
slick_laps = laps.pick_compounds(["SOFT", "MEDIUM", "HARD"])

# Green flag laps only
green_laps = laps.pick_track_status("1")

# Laps with any yellow flag
yellow_laps = laps.pick_track_status("4", how="contains")

# Safety car laps
sc_laps = laps.pick_track_status("6")

# Laps without pit stops
clean_laps = laps.pick_wo_box()

# Laps with pit entry
pit_in_laps = laps.pick_box_laps(which="in")

# Laps with pit exit
pit_out_laps = laps.pick_box_laps(which="out")

# Any pit activity
pit_laps = laps.pick_box_laps(which="both")

# Exclude deleted laps (lap time deleted by FIA)
valid_laps = laps.pick_not_deleted()

# Only accurate laps (high-quality timing data)
accurate_laps = laps.pick_accurate()

# Combine filters for cleanest data
clean_laps = laps.pick_not_deleted().pick_accurate().pick_wo_box()

# Get telemetry for all laps
tel = laps.get_telemetry()

# Equivalent methods
tel = laps.get_car_data()
tel = laps.get_pos_data()

# Access via property
tel = laps.telemetry

weather = laps.get_weather_data()
print(weather[["Time", "AirTemp", "TrackTemp", "Rainfall"]].head())

q1, q2, q3 = laps.split_qualifying_sessions()

print(f"Q1: {len(q1)} laps")
print(f"Q2: {len(q2)} laps")
print(f"Q3: {len(q3)} laps")

# Analyze each session separately
q3_fastest = q3.pick_fastest()

# Iterate over all laps
for idx, lap in laps.iterlaps():
    print(f"Lap {lap['LapNumber']}: {lap['LapTimeSeconds']:.3f}s")

# Require specific columns
for idx, lap in laps.iterlaps(require=["LapTime", "Driver", "Compound"]):
    print(f"{lap['Driver']} on {lap['Compound']}: {lap['LapTime']}")

# Access telemetry in loop
for idx, lap in laps.iterlaps():
    tel = lap.telemetry
    if not tel.empty:
        print(f"Lap {lap['LapNumber']}: max speed {tel['Speed'].max():.1f} km/h")

# Reset index and drop old index
laps_reset = laps.reset_index(drop=True)

# Reset index and keep as column
laps_with_old_index = laps.reset_index(drop=False)

ver_laps = laps.pick_driver("VER")
tel = ver_laps.telemetry  # All telemetry for VER's laps

# Raises ValueError for multi-driver laps
# tel = laps.telemetry  # ERROR if laps contains multiple drivers

import tif1

session = tif1.get_session(2024, "Monaco", "Race")
laps = session.laps

# Get clean racing laps for top 3 drivers on soft tires
clean_laps = (
    laps
    .pick_drivers(["VER", "HAM", "LEC"])
    .pick_tyre("SOFT")
    .pick_track_status("1")  # Green flag only
    .pick_not_deleted()
    .pick_accurate()
    .pick_wo_box()  # No pit stops
    .pick_quicklaps(threshold=1.05)  # Within 105% of fastest
)

print(f"Found {len(clean_laps)} clean laps")

# Analyze lap times by driver
for driver in ["VER", "HAM", "LEC"]:
    driver_laps = clean_laps.pick_driver(driver)
    if not driver_laps.empty:
        avg_time = driver_laps["LapTimeSeconds"].mean()
        print(f"{driver}: {avg_time:.3f}s average")

Lap(
    session: Session,
    driver: str,
    lap_number: int
)

def get_telemetry() -> DataFrame

lap = ver.get_lap(19)
tel = lap.get_telemetry()

# Analyze telemetry
print(f"Samples: {len(tel)}")
print(f"Max speed: {tel['Speed'].max()} km/h")
print(f"Max RPM: {tel['RPM'].max()}")

def get_car_data(**kwargs) -> DataFrame

def get_pos_data(**kwargs) -> DataFrame

def get_weather_data() -> DataFrame

import tif1

# Load session
session = tif1.get_session(2021, "Belgian Grand Prix", "Race")

# Access drivers
print(f"Drivers: {session.drivers}")

# Get all laps
laps = session.laps
print(f"Total laps: {len(laps)}")

# Get fastest laps
fastest = session.get_fastest_laps(by_driver=True)
print(fastest[["Driver", "LapTimeSeconds", "Compound"]].head())

# Get specific driver
ver = session.get_driver("VER")
print(f"Driver: {ver.driver}")
print(f"Team: {ver['TeamName']}")  # Access Series data
print(f"Number: {ver['DriverNumber']}")  # Access Series data

# Get driver's laps
ver_laps = ver.laps
print(f"Laps completed: {len(ver_laps)}")

# Get fastest lap
fastest = ver.get_fastest_lap()
print(f"Fastest: {fastest['LapTimeSeconds'].iloc[0]:.3f}s")

# Get fastest lap telemetry
tel = session.get_fastest_lap_tel()

# Analyze telemetry
# Available columns: Time, Speed, RPM, Throttle, Brake, nGear, DRS, X, Y, Z, Distance
print(f"Max speed: {tel['Speed'].max():.1f} km/h")
print(f"Max RPM: {tel['RPM'].max()}")
print(f"Avg throttle: {tel['Throttle'].mean():.1f}%")

# Find braking zones
braking = tel[tel['Brake'] == True]
print(f"Braking points: {len(braking)}")

# Plot speed trace
import matplotlib.pyplot as plt
plt.plot(tel['Distance'], tel['Speed'])
plt.xlabel('Distance (m)')
plt.ylabel('Speed (km/h)')
plt.show()

import asyncio
import tif1

async def load_session():
    session = tif1.get_session(2021, "Belgian Grand Prix", "Race")

    # Load laps in parallel
    laps = await session.laps_async()

    # Get telemetry for multiple drivers in parallel
    tels = await session.get_fastest_laps_tels_async(
        by_driver=True,
        drivers=["VER", "HAM", "BOT"]
    )

    for driver, tel in tels.items():
        print(f"{driver}: {tel['Speed'].max():.1f} km/h")

asyncio.run(load_session())

# Enable ultra-cold start for minimal latency
import tif1

# Configure ultra-cold mode globally
config = tif1.get_config()
config.ultra_cold = True

session = tif1.get_session(2021, "Belgian Grand Prix", "Qualifying")

# Get fastest lap telemetry with ultra-cold optimization
tel = session.get_fastest_lap_tel(ultra_cold=True)

# This skips loading all laps and goes directly to the fastest lap
print(f"Loaded in minimal time: {len(tel)} samples")

import tif1
from tif1.exceptions import DriverNotFoundError, LapNotFoundError, DataNotFoundError

try:
    session = tif1.get_session(2021, "Belgian Grand Prix", "Race")
    driver = session.get_driver("VER")
    lap = driver.get_lap(1)
    tel = lap.telemetry
    print(f"Lap 1 telemetry: {len(tel)} samples")
except DriverNotFoundError as e:
    print(f"Driver not found: {e}")
except LapNotFoundError as e:
    print(f"Lap not found: {e}")
except DataNotFoundError as e:
    print(f"Session data not available: {e}")

import time
import asyncio
import tif1

# Sync approach (slower)
start = time.time()
session = tif1.get_session(2021, "Belgian Grand Prix", "Race")
laps = session.laps  # Sequential loading
print(f"Sync: {time.time() - start:.2f}s")

# Async approach (faster)
async def load_async():
    start = time.time()
    session = tif1.get_session(2021, "Belgian Grand Prix", "Race")
    laps = await session.laps_async()  # Parallel loading
    print(f"Async: {time.time() - start:.2f}s")

asyncio.run(load_async())

# ❌ Wrong - drivers property returns numbers, not codes
drivers = session.drivers  # Returns ["1", "33", "44"]
driver = session.get_driver(drivers[0])  # May fail if "1" is not a valid code

# ✅ Correct - use drivers_df to get codes
drivers_df = session.drivers_df
driver_code = drivers_df.iloc[0]["Abbreviation"]  # Returns "VER"
driver = session.get_driver(driver_code)

# ✅ Also correct - get_driver() accepts both codes and numbers
driver = session.get_driver("VER")  # By code
driver = session.get_driver(33)     # By number

# ❌ Wrong - lap numbers start at 1, not 0
lap = driver.get_lap(0)  # Raises LapNotFoundError

# ✅ Correct - use 1-indexed lap numbers
lap = driver.get_lap(1)  # First lap

# Check if telemetry is available
tel = lap.get_telemetry()
if len(tel) == 0:
    print("No telemetry data available for this lap")
else:
    print(f"Telemetry loaded: {len(tel)} samples")

# ❌ Slow - sequential loading
for driver_code in ["VER", "HAM", "BOT"]:
    driver = session.get_driver(driver_code)
    tel = driver.get_fastest_lap_tel()

# ✅ Fast - parallel loading
tels = session.get_fastest_laps_tels(
    by_driver=True,
    drivers=["VER", "HAM", "BOT"]
)