Skip to main content
All JSON files in the F1 Stats Archive follow schemas based on the Ergast API format. This page documents the structure of each file type with real examples.

​
Common Structure

All JSON files share a common wrapper structure: 
{
  "MRData": {
    "xmlns": "",
    "series": "f1",
    "url": "https://api.jolpi.ca/ergast/f1/...",
    "limit": "30",
    "offset": "0",
    "total": "24",
    // Specific data tables here
  }
}
The MRData object contains metadata about the API response and wraps the actual race data.

​
Season-Level Files

Location: {year}/events.jsonDescription: Complete race calendar for the season with circuit information and session schedules.Schema:
{
  "MRData": {
    "RaceTable": {
      "season": "2024",
      "Races": [
        {
          "season": "2024",
          "round": "3",
          "url": "https://en.wikipedia.org/wiki/2024_Australian_Grand_Prix",
          "raceName": "Australian Grand Prix",
          "Circuit": {
            "circuitId": "albert_park",
            "url": "https://en.wikipedia.org/wiki/Albert_Park_Circuit",
            "circuitName": "Albert Park Grand Prix Circuit",
            "Location": {
              "lat": "-37.8497",
              "long": "144.968",
              "locality": "Melbourne",
              "country": "Australia"
            }
          },
          "date": "2024-03-24",
          "time": "04:00:00Z",
          "FirstPractice": {
            "date": "2024-03-22",
            "time": "01:30:00Z"
          },
          "SecondPractice": {
            "date": "2024-03-22",
            "time": "05:00:00Z"
          },
          "ThirdPractice": {
            "date": "2024-03-23",
            "time": "01:30:00Z"
          },
          "Qualifying": {
            "date": "2024-03-23",
            "time": "05:00:00Z"
          }
        }
      ]
    }
  }
}
Sprint Weekend Example:
{
  "season": "2024",
  "round": "5",
  "raceName": "Chinese Grand Prix",
  "date": "2024-04-21",
  "FirstPractice": {
    "date": "2024-04-19",
    "time": "03:30:00Z"
  },
  "Qualifying": {
    "date": "2024-04-20",
    "time": "07:00:00Z"
  },
  "Sprint": {
    "date": "2024-04-20",
    "time": "03:00:00Z"
  },
  "SprintQualifying": {
    "date": "2024-04-19",
    "time": "07:30:00Z"
  }
}
Sprint weekends have Sprint and SprintQualifying fields instead of SecondPractice and ThirdPractice.
Location: {year}/driverPoints.jsonDescription: Final driver championship standings for the season.Schema:
{
  "MRData": {
    "StandingsTable": {
      "season": "2024",
      "round": "24",
      "StandingsLists": [
        {
          "season": "2024",
          "round": "24",
          "DriverStandings": [
            {
              "position": "1",
              "positionText": "1",
              "points": "437",
              "wins": "9",
              "Driver": {
                "driverId": "max_verstappen",
                "permanentNumber": "33",
                "code": "VER",
                "url": "http://en.wikipedia.org/wiki/Max_Verstappen",
                "givenName": "Max",
                "familyName": "Verstappen",
                "dateOfBirth": "1997-09-30",
                "nationality": "Dutch"
              },
              "Constructors": [
                {
                  "constructorId": "red_bull",
                  "url": "http://en.wikipedia.org/wiki/Red_Bull_Racing",
                  "name": "Red Bull",
                  "nationality": "Austrian"
                }
              ]
            }
          ]
        }
      ]
    }
  }
}
Key Fields:
  • position: Championship position (1-20+)
  • points: Total points accumulated
  • wins: Number of race wins
  • driverId: Unique driver identifier (lowercase with underscores)
  • code: Three-letter driver code (e.g., VER, HAM, LEC)
Location: {year}/teamPoints.jsonDescription: Final constructor championship standings for the season.Schema:
{
  "MRData": {
    "StandingsTable": {
      "season": "2024",
      "round": "24",
      "StandingsLists": [
        {
          "season": "2024",
          "round": "24",
          "ConstructorStandings": [
            {
              "position": "1",
              "positionText": "1",
              "points": "666",
              "wins": "6",
              "Constructor": {
                "constructorId": "mclaren",
                "url": "http://en.wikipedia.org/wiki/McLaren",
                "name": "McLaren",
                "nationality": "British"
              }
            }
          ]
        }
      ]
    }
  }
}
Key Fields:
  • position: Championship position
  • points: Combined points from both drivers
  • wins: Number of race wins
  • constructorId: Unique team identifier

​
Race-Level Files

Location: {year}/{race-name}/event_info.jsonDescription: Race weekend information including circuit details and session schedule.Schema:
{
  "season": "2024",
  "round": "3",
  "url": "https://en.wikipedia.org/wiki/2024_Australian_Grand_Prix",
  "raceName": "Australian Grand Prix",
  "Circuit": {
    "circuitId": "albert_park",
    "url": "https://en.wikipedia.org/wiki/Albert_Park_Circuit",
    "circuitName": "Albert Park Grand Prix Circuit",
    "Location": {
      "lat": "-37.8497",
      "long": "144.968",
      "locality": "Melbourne",
      "country": "Australia"
    }
  },
  "date": "2024-03-24",
  "time": "04:00:00Z",
  "FirstPractice": {
    "date": "2024-03-22",
    "time": "01:30:00Z"
  },
  "SecondPractice": {
    "date": "2024-03-22",
    "time": "05:00:00Z"
  },
  "ThirdPractice": {
    "date": "2024-03-23",
    "time": "01:30:00Z"
  },
  "Qualifying": {
    "date": "2024-03-23",
    "time": "05:00:00Z"
  }
}
This is a simplified version of a single race entry from events.json.
Location: {year}/{race-name}/results.jsonDescription: Complete race results including finishing positions, times, and points.Schema:
{
  "MRData": {
    "RaceTable": {
      "season": "2024",
      "round": "3",
      "Races": [
        {
          "season": "2024",
          "round": "3",
          "raceName": "Australian Grand Prix",
          "date": "2024-03-24",
          "Results": [
            {
              "number": "55",
              "position": "1",
              "positionText": "1",
              "points": "25",
              "Driver": {
                "driverId": "sainz",
                "code": "SAI",
                "givenName": "Carlos",
                "familyName": "Sainz",
                "nationality": "Spanish"
              },
              "Constructor": {
                "constructorId": "ferrari",
                "name": "Ferrari",
                "nationality": "Italian"
              },
              "grid": "2",
              "laps": "58",
              "status": "Finished",
              "Time": {
                "millis": "4826843",
                "time": "1:20:26.843"
              },
              "FastestLap": {
                "rank": "3",
                "lap": "48",
                "Time": {
                  "time": "1:20.031"
                },
                "AverageSpeed": {
                  "units": "kph",
                  "speed": "237.418"
                }
              }
            }
          ]
        }
      ]
    }
  }
}
Key Fields:
  • position: Finishing position (or classification)
  • positionText: Position as text (“1”, “2”, “R” for retired, “D” for disqualified)
  • grid: Starting grid position
  • laps: Laps completed
  • status: “Finished”, “Retired”, “Lapped”, etc.
  • Time.millis: Race time in milliseconds (winner only)
  • Time.time: Race time or gap to winner
  • FastestLap: Driver’s fastest lap information
Location: {year}/{race-name}/quali_results.jsonDescription: Qualifying results showing times from Q1, Q2, and Q3 sessions.Schema:
{
  "MRData": {
    "RaceTable": {
      "season": "2024",
      "round": "3",
      "Races": [
        {
          "season": "2024",
          "round": "3",
          "raceName": "Australian Grand Prix",
          "date": "2024-03-24",
          "QualifyingResults": [
            {
              "number": "1",
              "position": "1",
              "Driver": {
                "driverId": "max_verstappen",
                "code": "VER",
                "givenName": "Max",
                "familyName": "Verstappen"
              },
              "Constructor": {
                "constructorId": "red_bull",
                "name": "Red Bull"
              },
              "Q1": "1:16.819",
              "Q2": "1:16.387",
              "Q3": "1:15.915"
            }
          ]
        }
      ]
    }
  }
}
Key Fields:
  • Q1: Fastest lap time in Q1 session
  • Q2: Fastest lap time in Q2 session (if reached)
  • Q3: Fastest lap time in Q3 session (if reached)
Drivers eliminated in Q1 only have Q1 times. Drivers eliminated in Q2 have Q1 and Q2 times. Top 10 drivers have all three times.
Location: {year}/{race-name}/laptimes.jsonDescription: Lap-by-lap timing data for every driver throughout the race.Schema:
{
  "MRData": {
    "RaceTable": {
      "season": "2024",
      "round": "3",
      "Races": [
        {
          "season": "2024",
          "round": "3",
          "raceName": "Australian Grand Prix",
          "date": "2024-03-24",
          "Laps": [
            {
              "number": "1",
              "Timings": [
                {
                  "driverId": "max_verstappen",
                  "position": "1",
                  "time": "1:27.458"
                },
                {
                  "driverId": "sainz",
                  "position": "2",
                  "time": "1:28.375"
                }
              ]
            },
            {
              "number": "2",
              "Timings": [
                // Lap 2 times...
              ]
            }
          ]
        }
      ]
    }
  }
}
Key Fields:
  • number: Lap number
  • Timings: Array of all drivers’ times for this lap
  • position: Position at the end of this lap
  • time: Lap time
This file can be very large (100+ KB) for modern races with 50+ laps and 20 drivers.
Location: {year}/{race-name}/pitstops.jsonDescription: All pit stop data including lap number, stop duration, and time of day.Schema:
{
  "MRData": {
    "RaceTable": {
      "season": "2024",
      "round": "3",
      "Races": [
        {
          "season": "2024",
          "round": "3",
          "raceName": "Australian Grand Prix",
          "date": "2024-03-24",
          "PitStops": [
            {
              "driverId": "ricciardo",
              "lap": "5",
              "stop": "1",
              "time": "15:10:25",
              "duration": "18.265"
            },
            {
              "driverId": "albon",
              "lap": "6",
              "stop": "1",
              "time": "15:11:45",
              "duration": "17.755"
            }
          ]
        }
      ]
    }
  }
}
Key Fields:
  • lap: Lap number when pit stop occurred
  • stop: Stop number for this driver (1, 2, 3, etc.)
  • time: Local time of day (HH:MM:SS)
  • duration: Pit stop duration in seconds
Use duration to compare pit stop efficiency across teams and races.
Location: {year}/{race-name}/sprint_results.json (sprint weekends only)Description: Sprint race results with positions, times, and points awarded.Schema:
{
  "MRData": {
    "RaceTable": {
      "season": "2024",
      "round": "5",
      "Races": [
        {
          "season": "2024",
          "round": "5",
          "raceName": "Chinese Grand Prix",
          "date": "2024-04-21",
          "SprintResults": [
            {
              "number": "1",
              "position": "1",
              "positionText": "1",
              "points": "8",
              "Driver": {
                "driverId": "max_verstappen",
                "code": "VER",
                "givenName": "Max",
                "familyName": "Verstappen"
              },
              "Constructor": {
                "constructorId": "red_bull",
                "name": "Red Bull"
              },
              "grid": "4",
              "laps": "19",
              "status": "Finished",
              "Time": {
                "millis": "1924660",
                "time": "32:04.660"
              },
              "FastestLap": {
                "rank": "1",
                "lap": "3",
                "Time": {
                  "time": "1:40.331"
                }
              }
            }
          ]
        }
      ]
    }
  }
}
Sprint Points (2024):
  • 1st: 8 points
  • 2nd: 7 points
  • 3rd: 6 points
  • 4th: 5 points
  • 5th: 4 points
  • 6th: 3 points
  • 7th: 2 points
  • 8th: 1 point
Sprint race format and points have changed over the years. Always check the points field for actual points awarded.

​
Common Data Types

​
Driver Object

Appears in all race data: 
{
  "driverId": "max_verstappen",
  "permanentNumber": "33",
  "code": "VER",
  "url": "http://en.wikipedia.org/wiki/Max_Verstappen",
  "givenName": "Max",
  "familyName": "Verstappen",
  "dateOfBirth": "1997-09-30",
  "nationality": "Dutch"
}

​
Constructor Object

Appears in all race data: 
{
  "constructorId": "red_bull",
  "url": "http://en.wikipedia.org/wiki/Red_Bull_Racing",
  "name": "Red Bull",
  "nationality": "Austrian"
}

​
Circuit Object

Appears in event files: 
{
  "circuitId": "albert_park",
  "url": "https://en.wikipedia.org/wiki/Albert_Park_Circuit",
  "circuitName": "Albert Park Grand Prix Circuit",
  "Location": {
    "lat": "-37.8497",
    "long": "144.968",
    "locality": "Melbourne",
    "country": "Australia"
  }
}

​
Time Object

Appears in results: 
{
  "millis": "4826843",
  "time": "1:20:26.843"
}

​
Data Validation

Field PresenceNot all fields are guaranteed to exist in every record:
  • FastestLap may be missing for retired drivers
  • Time may be missing for non-finishers
  • AverageSpeed appears inconsistently
  • Historical data may have fewer fields
Consistent IdentifiersUse these IDs for consistent lookups across files:
  • driverId: “max_verstappen”, “hamilton”, “leclerc”
  • constructorId: “red_bull”, “ferrari”, “mclaren”
  • circuitId: “monaco”, “silverstone”, “monza”

​
Next Steps

Data Structure Overview

Return to the overview for navigation guidance

Directory Layout

See how files are organized on disk

Build docs developers (and LLMs) love

Get started for freeTalk to us