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

1. Clone the repository

   Clone the F1 Stats Archive repository to your local machine:

   git clone <your-repo-url>
   cd f1-stats-archive
   
2. Install dependencies

   Install the required Python packages using pip:

   pip install -r requirements.txt
   

   The project only requires the requests library for making API calls.

3. Fetch race events

   Start by fetching race events for a season. Run the events script to get all races for 2026:

   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

   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.

4. Fetch race results

   Now fetch the actual race results for a specific round:

   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

   Fetch a specific round

   from results import RaceResultsFetcher
   
   fetcher = RaceResultsFetcher(base_dir=".")
   fetcher.fetch_round(2026, 1)  # Fetch Round 1 of 2026
   
5. 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

Example: Fetch Complete Race Data

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

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:

{
  "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"
              }
            }
          ]
        }
      ]
    }
  }
}

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.

Next Steps

Installation

Learn about detailed installation and configuration options

API Reference

Explore all available scripts and their parameters