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

# Quick Start

> Get started with F1 Stats Archive in minutes

Get F1 Stats Archive up and running in just a few minutes. This guide will help you fetch your first Formula 1 race data from the Ergast API.

## Prerequisites

Before you begin, make sure you have:

* Python 3.7 or higher installed
* Git installed on your system
* An internet connection to access the Ergast API

<Steps>
  <Step title="Clone the repository">
    Clone the F1 Stats Archive repository to your local machine:

    ```bash theme={null}
    git clone <your-repo-url>
    cd f1-stats-archive
    ```
  </Step>

  <Step title="Install dependencies">
    Install the required Python packages using pip:

    ```bash theme={null}
    pip install -r requirements.txt
    ```

    The project only requires the `requests` library for making API calls.
  </Step>

  <Step title="Fetch race events">
    Start by fetching race events for a season. Run the events script to get all races for 2026:

    ```bash theme={null}
    python events.py
    ```

    This script will:

    * Create a directory structure organized by year
    * Fetch all race events for the specified season(s)
    * Save event data to `events.json` in each year folder
    * Create individual folders for each race

    <Note>
      By default, the script is configured to fetch 2026 data. You can modify the `start_year` and `end_year` variables in `events.py` to fetch different seasons.
    </Note>
  </Step>

  <Step title="Fetch race results">
    Now fetch the actual race results for a specific round:

    ```bash theme={null}
    python results.py
    ```

    The `RaceResultsFetcher` class handles:

    * Rate limiting (4 requests per second)
    * Automatic retry on rate limit errors
    * Organized folder structure by season and race

    <CodeGroup>
      ```python Fetch a specific round theme={null}
      from results import RaceResultsFetcher

      fetcher = RaceResultsFetcher(base_dir=".")
      fetcher.fetch_round(2026, 1)  # Fetch Round 1 of 2026
      ```

      ```python Fetch multiple rounds theme={null}
      from results import RaceResultsFetcher

      fetcher = RaceResultsFetcher(base_dir=".")
      for round_num in range(1, 6):
          fetcher.fetch_round(2026, round_num)
      ```
    </CodeGroup>
  </Step>

  <Step title="Explore the data">
    Your data is now organized in a structured folder hierarchy:

    ```
    2026/
    ├── events.json
    └── australian-grand-prix/
        ├── event_info.json
        ├── results.json
        ├── quali_results.json
        ├── driverPoints.json
        └── laptimes.json
    ```

    Each race folder contains JSON files with different data types:

    * `results.json` - Race finishing positions and details
    * `quali_results.json` - Qualifying session results
    * `driverPoints.json` - Driver championship standings after this race
    * `laptimes.json` - Lap-by-lap timing data
  </Step>
</Steps>

## Example: Fetch Complete Race Data

Here's a complete example to fetch all data for a specific race:

```python theme={null}
from results import RaceResultsFetcher
from quali_results import QualifyingResultsFetcher
from driver_points import process_round
from laptimes import main as fetch_laptimes

season = 2026
round_num = 1

# Fetch race results
results_fetcher = RaceResultsFetcher(base_dir=".")
results_fetcher.fetch_round(season, round_num)

# Fetch qualifying results
quali_fetcher = QualifyingResultsFetcher(base_dir=".")
quali_fetcher.fetch_round(season, round_num)

# Fetch driver standings
process_round(season, round_num)

# Fetch lap times
fetch_laptimes(season, round_num)
```

## Understanding the Data Structure

The Ergast API returns data in a nested JSON structure. Here's what a typical race result looks like:

```json theme={null}
{
  "MRData": {
    "RaceTable": {
      "Races": [
        {
          "season": "2026",
          "round": "1",
          "raceName": "Australian Grand Prix",
          "Results": [
            {
              "position": "1",
              "Driver": {
                "driverId": "verstappen",
                "givenName": "Max",
                "familyName": "Verstappen"
              },
              "Constructor": {
                "constructorId": "red_bull",
                "name": "Red Bull"
              },
              "Time": {
                "time": "1:32:14.789"
              }
            }
          ]
        }
      ]
    }
  }
}
```

<Warning>
  The Ergast API has rate limits of 4 requests per second and 500 requests per hour. All scripts include automatic rate limiting to stay within these bounds.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Learn about detailed installation and configuration options
  </Card>

  <Card title="API Reference" icon="code" href="/api/events">
    Explore all available scripts and their parameters
  </Card>
</CardGroup>