> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/theOehrly/Fast-F1/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
pip install fastf1
```

## Basic Workflow

<Steps>
  <Step title="Import and configure cache">
    Always enable the cache before loading any data to improve performance and avoid rate limits.

    ```python theme={null}
    import fastf1

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

    <Warning>
      Call `Cache.enable_cache()` immediately after imports and before any other FastF1 functionality.
    </Warning>
  </Step>

  <Step title="Load a session">
    Use `get_session()` to create a session object, then call `load()` to fetch the data.

    ```python theme={null}
    # 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()
    ```

    <Tip>
      Session identifiers can be: `'FP1'`, `'FP2'`, `'FP3'`, `'Q'` (Qualifying), `'S'` (Sprint), `'SQ'` (Sprint Qualifying), or `'R'` (Race).
    </Tip>
  </Step>

  <Step title="Access lap data">
    The `session.laps` DataFrame contains all lap information for all drivers.

    ```python theme={null}
    # 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']}")
    ```
  </Step>

  <Step title="Access telemetry data">
    Retrieve high-frequency telemetry data for individual laps.

    ```python theme={null}
    # 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
  </Step>
</Steps>

## Complete Example: Lap Time Analysis

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

<CodeGroup>
  ```python Basic Analysis theme={null}
  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}")
  ```

  ```python With Visualization theme={null}
  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()
  ```

  ```python Telemetry Comparison theme={null}
  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()
  ```
</CodeGroup>

## Common Data Access Patterns

### Get Session Information

```python theme={null}
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

```python theme={null}
# 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

```python theme={null}
# 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'`

```python theme={null}
# 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

<Tip>
  **Always enable caching** - The first load will download data, but subsequent loads will be nearly instantaneous.
</Tip>

<Tip>
  **Use pick methods** - Methods like `pick_drivers()`, `pick_fastest()`, and `pick_quicklaps()` are optimized for filtering lap data.
</Tip>

<Tip>
  **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.
</Tip>

## Troubleshooting

### Rate Limit Errors

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

```python theme={null}
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:

```python theme={null}
try:
    session.load()
except Exception as e:
    print(f"Error loading session: {e}")
```

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api/session">
    Explore detailed API documentation for all classes and methods
  </Card>

  <Card title="Examples" icon="chart-line" href="/examples/overview">
    Browse more examples including advanced visualizations and analysis techniques
  </Card>
</CardGroup>