Skip to main content

​
Overview

The tif1 library provides a simple, intuitive API for accessing Formula 1 data. This guide covers the fundamental data access patterns you’ll use in most analyses.

​
Getting Events

Before accessing session data, you need to know which events are available: 
import tif1

# Get all events for a season
events_2025 = tif1.get_events(2025)
print(f"2025 Season: {len(events_2025)} events")

for event in events_2025[:5]:
    print(f"  • {event}")

​
Get Event by Round Number

Access specific events using their round number: 
# Get event by round number
event = tif1.get_event_by_round(2025, 10)
print(f"Round 10: {event['EventName']}")
print(f"Location: {event['Location']}, {event['Country']}")
print(f"Date: {event['EventDate']}")

​
Get Event by Name (Fuzzy Match)

The library supports fuzzy matching for event names, making it easy to find events: 
# Exact match (case insensitive)
event = tif1.get_event_by_name(2025, "British Grand Prix", exact_match=True)

# Fuzzy match by location
event = tif1.get_event(2025, "Silverstone")

# Fuzzy match by country
event = tif1.get_event(2025, "Great Britain")

# Fuzzy match by partial name
event = tif1.get_event(2025, "Monaco")

​
Getting Sessions

Once you have an event, check available sessions: 
# Get available sessions for an event
sessions = tif1.get_sessions(2025, "Abu Dhabi Grand Prix")
print("Available sessions:")
for session in sessions:
    print(f"  • {session}")

# Common session types:
# - "Practice 1", "Practice 2", "Practice 3"
# - "Qualifying"
# - "Sprint Qualifying" (sprint weekends)
# - "Sprint" (sprint weekends)
# - "Race"

​
Loading Session Data

Get a session object to access all session data: 
# Load a session
session = tif1.get_session(2025, "Abu Dhabi Grand Prix", "Practice 1")

# Access driver information
print(f"Drivers: {len(session.drivers_df)}")
print(session.drivers_df.head())
The drivers_df DataFrame contains:
  • Driver: 3-letter driver code (e.g., “VER”, “HAM”)
  • Team: Team name
  • DriverNumber: Driver’s racing number
  • FullName: Driver’s full name

​
Getting Laps

Access lap data for all drivers or specific drivers: 
# Get all laps in the session
laps = session.laps
print(f"Total laps: {len(laps)}")
print(laps[["Driver", "LapNumber", "LapTime", "Compound", "Stint"]].head(10))

​
Lap Data Columns

The laps DataFrame includes:
  • LapTime: Lap time in seconds
  • LapNumber: Lap number
  • Compound: Tire compound (SOFT, MEDIUM, HARD, INTERMEDIATE, WET)
  • Stint: Stint number
  • Sector1Time, Sector2Time, Sector3Time: Sector times in seconds
  • TyreLife: Tire age in laps
  • Position: Track position
  • TrackStatus: Track status (1=clear, 2=yellow, 4=SC, 5=red, 6=VSC)
  • IsPersonalBest: Personal best lap flag
  • Driver: Driver code
  • Team: Team name

​
Getting Driver-Specific Data

Access data for individual drivers: 
# Get driver object
ver = session.get_driver("VER")

# Get driver's laps
ver_laps = ver.laps
print(f"VER completed {len(ver_laps)} laps")
print(ver_laps[["lap", "time", "compound", "s1", "s2", "s3"]].head())

​
Filtering Laps

Filter laps based on various criteria: 
# Filter by driver
ver_laps = laps[laps["Driver"] == "VER"]

# Filter by compound
soft_laps = laps[laps["Compound"] == "SOFT"]

# Filter by lap time (valid laps only)
import numpy as np
valid_laps = laps[laps["LapTime"].notna()]

# Filter fastest laps per stint
fastest_per_stint = (
    valid_laps.groupby(["Driver", "Stint"])
    .apply(lambda x: x.loc[x["LapTime"].idxmin()])
    .reset_index(drop=True)
)

# Filter by track status (green flag only)
green_flag_laps = laps[laps["TrackStatus"] == 1]

​
Getting Telemetry

Access detailed telemetry data for specific laps: 
# Get a specific lap
lap_19 = ver.get_lap(19)

# Get telemetry for that lap
telemetry = lap_19.telemetry
print(f"Telemetry points: {len(telemetry)}")
print(telemetry[["Time", "Speed", "Throttle", "Brake", "RPM", "nGear"]].head(10))

​
Telemetry Data Columns

Telemetry DataFrame includes:
  • Time: Time in seconds from lap start
  • RPM: Engine RPM
  • Speed: Speed in km/h
  • nGear: Gear number (0-8)
  • Throttle: Throttle position (0-100%)
  • Brake: Brake status (0=off, 1=on)
  • DRS: DRS status (0=off, 1=on)
  • Distance: Distance in meters from start line
  • RelativeDistance: Relative distance (0-1 normalized)
  • X, Y, Z: Position coordinates
  • AccelerationX: Lateral acceleration (m/s²)
  • AccelerationY: Longitudinal acceleration (m/s²)
  • AccelerationZ: Vertical acceleration (m/s²)

​
Complete Example

Here’s a complete workflow for accessing and analyzing data: 
import tif1

# 1. Discover available events
events = tif1.get_events(2025)
print(f"Found {len(events)} events for 2025")

# 2. Get available sessions
sessions = tif1.get_sessions(2025, "Abu Dhabi Grand Prix")
print(f"Available sessions: {sessions}")

# 3. Load session
session = tif1.get_session(2025, "Abu Dhabi Grand Prix", "Practice 1")

# 4. Check available drivers
drivers_df = session.drivers_df
print(f"Drivers in session: {len(drivers_df)}")

# 5. Get specific driver
if "VER" in drivers_df["Driver"].values:
    ver = session.get_driver("VER")
    ver_laps = ver.laps
    
    if len(ver_laps) > 0:
        # 6. Get first lap
        first_lap_num = ver_laps["lap"].iloc[0]
        lap = ver.get_lap(int(first_lap_num))
        
        # 7. Access telemetry
        telemetry = lap.telemetry
        print(f"Loaded telemetry: {len(telemetry)} points")
        
        # 8. Analyze data
        max_speed = telemetry["Speed"].max()
        max_rpm = telemetry["RPM"].max()
        print(f"Max speed: {max_speed:.1f} km/h")
        print(f"Max RPM: {max_rpm:.0f}")

​
Next Steps