API Overview

​

Quick Start

import tif1

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

# Get all laps
laps = session.laps

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

# Get fastest lap telemetry
telemetry = driver.get_fastest_lap_tel()

​

Entry Points

​

Core Objects

​

Primary Objects

• Session: Represents an entire F1 session. Contains all laps, drivers, weather, and race control data.
• Driver: Represents a specific driver within a session. Provides convenient access to driver-specific data.
• Lap: Represents a single lap by a driver, containing high-frequency telemetry data.

​

Data Models

• Laps: Collection of lap data with filtering methods
• Telemetry: High-frequency telemetry data (Speed, RPM, Throttle, etc.)
• SessionResults: Final classification and results
• CircuitInfo: Circuit metadata and track information

​

API Categories

​

Core data access

• Core API - Session, Driver, Lap classes and data loading
• Models - Data model classes and structures
• Events - Event and session discovery
• Schedule - Schedule validation and schema

​

Data Pipeline

• I/O Pipeline - DataFrame construction and transformation
• Async Fetch - Parallel HTTP fetching with niquests
• HTTP - HTTP session and networking
• HTTP Session - Connection pooling and DoH support
• CDN - Multi-source CDN management with fallback

​

Configuration & Cache

• Config - Global configuration management
• Cache - SQLite-backed caching system
• Retry - Circuit breaker and retry logic

​

Visualization & Tools

• Plotting - F1-themed visualization utilities
• CLI - Command-line interface
• Jupyter - Notebook integration and rich displays

​

Utilities & Helpers

• Utils - General utility functions
• Utilities - Helper functions for configuration and logging
• Core Utils - Internal utilities for DataFrame operations
• Types - Type definitions and hints
• Validation - Pydantic models and data validation
• Fuzzy - Fuzzy string matching for event/session names
• Lap Operations - Utilities for working with lap data

​

Compatibility & Errors

• FastF1 Compat - FastF1 compatibility layer
• Exceptions - Exception hierarchy and error handling

​

Common Workflows

​

Load and explore session

import tif1

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

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

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

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

​

Analyze driver performance

import tif1

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

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

# 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['LapTime'].iloc[0]:.3f}s")

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

​

Parallel data loading

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", "RUS"]
    )

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

asyncio.run(load_session())

​

Configuration and Optimization

import tif1

# Get config
config = tif1.get_config()

# Use polars lib for better performance
config.set("lib", "polars")

# Enable ultra-cold start for minimal latency
config.set("ultra_cold_start", True)

# Increase concurrency
config.set("max_workers", 100)

# Save configuration
config.save()

​

Error Handling

​

Exception Hierarchy

TIF1Error (base)
├── DataNotFoundError
│   ├── DriverNotFoundError
│   └── LapNotFoundError
├── NetworkError
├── InvalidDataError
├── CacheError
└── SessionNotLoadedError

​

Common Exceptions

• DataNotFoundError: The requested GP, year, or session doesn’t exist
• NetworkError: All CDN sources failed or timed out
• InvalidDataError: The data fetched from the CDN was corrupted
• DriverNotFoundError: The driver code provided is not in this session
• LapNotFoundError: The requested lap number does not exist for this driver
• CacheError: Cache operation failed
• SessionNotLoadedError: Attempted to access data before loading session

​

Error handling example

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

try:
    session = tif1.get_session(2021, "Belgian Grand Prix", "Race")
    driver = session.get_driver("VER")
    lap = driver.get_lap(1)

except DataNotFoundError as e:
    print(f"Data not found: {e.message}")
    print(f"Context: {e.context}")

except NetworkError as e:
    print(f"Network error: {e.message}")
    print(f"URL: {e.context.get('url')}")

except DriverNotFoundError as e:
    print(f"Driver not found: {e.message}")
    print(f"Available drivers: {session.drivers}")

​

Performance Tips

1. Use async methods for parallel loading: 5-10x faster than sequential
   laps = await session.laps_async()
   
2. Enable ultra-cold start for single queries: Minimal latency
   config.set("ultra_cold_start", True)
   
3. Use polars lib for large datasets: Better memory efficiency
   config.set("lib", "polars")
   
4. Disable validation in production: 10-15% performance boost
   config.set("validate_data", False)
   
5. Increase concurrency for bulk operations: Faster parallel fetching
   config.set("max_workers", 100)
   

​

Type Hints

from tif1 import Session, Driver
from tif1.core import Lap
import pandas as pd

session: Session = tif1.get_session(2021, "Belgian Grand Prix", "Race")
driver: Driver = session.get_driver("VER")
lap: Lap = driver.get_lap(1)
laps: pd.DataFrame = session.laps
telemetry: pd.DataFrame = lap.telemetry

​

Next Steps

• Core API - Start with Session, Driver, and Lap classes
• Tutorials - Learn through practical examples
• Best Practices - Optimize your code
• FAQ - Common questions and answers

​

Related Pages