Skip to main content
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
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

Build docs developers (and LLMs) love

Get started for freeTalk to us