Quickstart

Load your first F1 session and access timing data, telemetry, and lap information

This guide walks you through loading a Formula 1 session and accessing timing data, telemetry, and lap information.

Prerequisites

Ensure FastF1 is installed and the cache is configured:

pip install fastf1

Basic Workflow

1. Import and configure cache

   Always enable the cache before loading any data to improve performance and avoid rate limits.

   import fastf1
   
   # Enable cache - replace with your preferred directory
   fastf1.Cache.enable_cache('~/fastf1_cache')
   

   Call Cache.enable_cache() immediately after imports and before any other FastF1 functionality.

2. Load a session

   Use get_session() to create a session object, then call load() to fetch the data.

   # Get the 2023 Azerbaijan Grand Prix Race session
   session = fastf1.get_session(2023, 'Azerbaijan', 'R')
   
   # Load all session data (timing, telemetry, weather, etc.)
   session.load()
   

   Session identifiers can be: 'FP1', 'FP2', 'FP3', 'Q' (Qualifying), 'S' (Sprint), 'SQ' (Sprint Qualifying), or 'R' (Race).

3. Access lap data

   The session.laps DataFrame contains all lap information for all drivers.

   # Get all laps for a specific driver
   alonso_laps = session.laps.pick_drivers('ALO')
   
   # Filter for quick laps only (removes outliers)
   quick_laps = alonso_laps.pick_quicklaps()
   
   # Get the fastest lap
   fastest_lap = alonso_laps.pick_fastest()
   
   print(f"Fastest lap time: {fastest_lap['LapTime']}")
   print(f"Lap number: {fastest_lap['LapNumber']}")
   print(f"Compound: {fastest_lap['Compound']}")
   
4. Access telemetry data

   Retrieve high-frequency telemetry data for individual laps.

   # Get telemetry for the fastest lap
   telemetry = fastest_lap.get_car_data()
   
   # Add distance column for easier analysis
   telemetry = telemetry.add_distance()
   
   # Access telemetry channels
   print(telemetry[['Distance', 'Speed', 'Throttle', 'Brake', 'nGear']].head())
   

   Available telemetry channels:

   • Speed: Car speed (km/h)
   • RPM: Engine RPM
   • nGear: Gear number
   • Throttle: Throttle position (0-100%)
   • Brake: Brake applied (boolean)
   • DRS: DRS status
   • X, Y, Z: GPS position coordinates

Complete Example: Lap Time Analysis

Here’s a complete example that loads a session and analyzes driver lap times:

Basic Analysis

import fastf1
import pandas as pd

# Configure cache
fastf1.Cache.enable_cache('~/fastf1_cache')

# Load session
session = fastf1.get_session(2023, 'Azerbaijan', 'R')
session.load()

# Get laps for a driver
driver_laps = session.laps.pick_drivers('ALO').pick_quicklaps()

# Display lap time statistics
print(f"Total laps: {len(driver_laps)}")
print(f"Fastest lap: {driver_laps['LapTime'].min()}")
print(f"Average lap time: {driver_laps['LapTime'].mean()}")

# Show compound usage
compound_usage = driver_laps.groupby('Compound').size()
print(f"\nCompound usage:\n{compound_usage}")

import fastf1
import fastf1.plotting
import matplotlib.pyplot as plt
import seaborn as sns

# Setup plotting
fastf1.plotting.setup_mpl(mpl_timedelta_support=True, color_scheme='fastf1')

# Configure cache and load session
fastf1.Cache.enable_cache('~/fastf1_cache')
session = fastf1.get_session(2023, 'Azerbaijan', 'R')
session.load()

# Get driver laps
driver_laps = session.laps.pick_drivers('ALO').pick_quicklaps().reset_index()

# Create scatter plot
fig, ax = plt.subplots(figsize=(10, 6))

sns.scatterplot(
    data=driver_laps,
    x='LapNumber',
    y='LapTime',
    hue='Compound',
    palette=fastf1.plotting.get_compound_mapping(session=session),
    s=80,
    ax=ax
)

ax.set_xlabel('Lap Number')
ax.set_ylabel('Lap Time')
ax.invert_yaxis()
plt.title('Alonso Lap Times - 2023 Azerbaijan GP')
plt.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()

import fastf1
import fastf1.plotting
import matplotlib.pyplot as plt

# Setup
fastf1.plotting.setup_mpl(mpl_timedelta_support=True, color_scheme='fastf1')
fastf1.Cache.enable_cache('~/fastf1_cache')

# Load session
session = fastf1.get_session(2021, 'Spanish Grand Prix', 'Q')
session.load()

# Get fastest laps for two drivers
ver_lap = session.laps.pick_drivers('VER').pick_fastest()
ham_lap = session.laps.pick_drivers('HAM').pick_fastest()

# Get telemetry with distance
ver_tel = ver_lap.get_car_data().add_distance()
ham_tel = ham_lap.get_car_data().add_distance()

# Get team colors
rbr_color = fastf1.plotting.get_team_color(ver_lap['Team'], session=session)
mer_color = fastf1.plotting.get_team_color(ham_lap['Team'], session=session)

# Plot speed comparison
fig, ax = plt.subplots(figsize=(12, 6))
ax.plot(ver_tel['Distance'], ver_tel['Speed'], color=rbr_color, label='VER')
ax.plot(ham_tel['Distance'], ham_tel['Speed'], color=mer_color, label='HAM')

ax.set_xlabel('Distance (m)')
ax.set_ylabel('Speed (km/h)')
ax.legend()
plt.title('Fastest Lap Comparison - Spanish GP 2021 Qualifying')
plt.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()

Common Data Access Patterns

Get Session Information

session = fastf1.get_session(2023, 5, 'Q')
session.load()

print(f"Event: {session.event['EventName']}")
print(f"Location: {session.event['Location']}")
print(f"Date: {session.event['EventDate']}")
print(f"Session: {session.name}")

Filter and Select Laps

# Multiple drivers
laps = session.laps.pick_drivers(['HAM', 'VER', 'LEC'])

# Specific lap number
lap_1 = session.laps.pick_laps(1)

# Fastest lap per driver
fastest_laps = session.laps.pick_fastest()

# Laps on a specific compound
soft_laps = session.laps[session.laps['Compound'] == 'SOFT']

Access Results and Classification

# Get final race results
results = session.results
print(results[['DriverNumber', 'Abbreviation', 'TeamName', 'Position']])

# Get weather data
weather = session.weather_data
print(weather[['Time', 'AirTemp', 'TrackTemp', 'Rainfall']].head())

Understanding Session Identifiers

FastF1 accepts multiple formats for identifying sessions:

Abbreviation	Full Name	Description
'FP1'	Practice 1	First practice session
'FP2'	Practice 2	Second practice session
'FP3'	Practice 3	Third practice session
'Q'	Qualifying	Qualifying session
'S'	Sprint	Sprint race
'SQ'	Sprint Qualifying	Sprint qualifying
'SS'	Sprint Shootout	Sprint shootout
'R'	Race	Main race

You can also use:

• Session number (integer): Sessions are numbered in chronological order
• Full session name (string): e.g., 'Qualifying', 'Race'

# All equivalent ways to get qualifying
session = fastf1.get_session(2023, 'Monaco', 'Q')
session = fastf1.get_session(2023, 'Monaco', 'Qualifying')
session = fastf1.get_session(2023, 'Monaco', 4)  # 4th session of weekend

Performance Tips

Always enable caching - The first load will download data, but subsequent loads will be nearly instantaneous.

Use pick methods - Methods like pick_drivers(), pick_fastest(), and pick_quicklaps() are optimized for filtering lap data.

Load only what you need - If you only need timing data, you can skip telemetry by using session.load(telemetry=False, weather=False) for faster loading.

Troubleshooting

Rate Limit Errors

If you encounter rate limit errors, ensure caching is enabled:

fastf1.Cache.enable_cache('~/fastf1_cache')

FastF1 enforces rate limits:

• 4 requests/second (minimum 0.25s between requests)
• 200 requests/hour for Ergast API
• 500 requests/hour for other APIs

No Data Available

Some sessions may have incomplete data, especially for older seasons (pre-2018) or testing sessions. Check the session’s available data:

try:
    session.load()
except Exception as e:
    print(f"Error loading session: {e}")

Next Steps

API Reference

Explore detailed API documentation for all classes and methods

Examples

Browse more examples including advanced visualizations and analysis techniques