Ergast APIergast.com ↗
Access Formula 1 data from 1950 to present via 19 endpoints covering race results, standings, lap times, pit stops, drivers, and constructors.
What is the Ergast API?
The Ergast API mirror exposes 19 endpoints covering every layer of Formula 1 data from the 1950 season onward — race schedules, qualifying times, championship standings, lap-by-lap timing, and pit stop records. Endpoints like get_race_results return finishing positions, points, and fastest laps for all drivers in a given round, while get_lap_times delivers per-lap per-driver timing data for any race in the historical archive.
curl -X GET 'https://api.parse.bot/scraper/bd695366-8089-4ae0-a38a-7263d35d59f3/get_seasons?limit=5&offset=0' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace ergast-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Formula 1 Data API — bounded, re-runnable; every call capped."""
from parse_apis.formula_1_data_api import F1, ResourceNotFound
client = F1()
# List recent seasons
for season in client.seasons.list(limit=5):
print(season.season, season.url)
# Get a specific driver by ID and explore their seasons
driver = client.drivers.get(driver_id="hamilton")
print(driver.given_name, driver.family_name, driver.nationality)
# Walk the driver's seasons (instance method)
for s in driver.seasons(limit=3):
print(s.season, s.url)
# List constructors for 2023 season
for team in client.constructors.list(season="2023", limit=3):
print(team.name, team.nationality)
# Get race results
result = client.raceresults.list(season="2023", round="1", limit=1).first()
if result:
print(result.race_name, result.season, result.round)
# Typed error handling: attempt to look up a nonexistent driver
try:
client.drivers.get(driver_id="nonexistent_driver_xyz")
except ResourceNotFound as exc:
print(f"Driver not found: {exc}")
print("exercised: seasons.list / drivers.get / driver.seasons / constructors.list / raceresults.list / error handling")
Get a list of all F1 seasons supported by the API. Returns season years with Wikipedia links. Supports pagination via limit and offset.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of results to return. |
| offset | integer | Result offset for pagination. |
{
"type": "object",
"fields": {
"total": "string total count of available seasons",
"seasons": "array of season objects each with season year string and Wikipedia url"
},
"sample": {
"data": {
"total": "77",
"seasons": [
{
"url": "https://en.wikipedia.org/wiki/1950_Formula_One_season",
"season": "1950"
},
{
"url": "https://en.wikipedia.org/wiki/1951_Formula_One_season",
"season": "1951"
}
]
},
"status": "success"
}
}About the Ergast API
Race, Qualifying, and Timing Data
get_race_results accepts a season (year or 'current') and round (number or 'last') and returns a RaceTable containing each driver's finishing position, points scored, and timing details including fastest laps. get_qualifying_results returns Q1, Q2, and Q3 lap times for the same round parameters. For granular analysis, get_lap_times accepts an optional lap_number and returns a Laps array with individual Timings entries per driver. get_pit_stops lets you filter by stop_number — useful for isolating all first stops across a race — and returns lap, stop number, wall-clock time, and duration for each stop.
Standings and Season Coverage
get_driver_standings and get_constructor_standings both accept a round parameter so you can reconstruct the championship table at any point mid-season, not just at the year's end. get_seasons_for_driver and get_seasons_for_constructor return the full list of seasons a given driver_id or constructor_id appeared in, which is useful for computing career spans without iterating every season manually.
Reference Data — Drivers, Constructors, Circuits
get_drivers returns driverId, three-letter code, full name, dateOfBirth, and nationality. All list endpoints support limit and offset for pagination. get_circuit_info returns a Location object with latitude, longitude, locality, and country for a given circuit_id. get_finishing_status returns all status codes (Finished, Accident, +1 Lap, etc.) with counts, optionally scoped to a season or a specific round — useful for reliability analysis across teams or eras.
Filtering by Driver or Constructor
get_driver_season_results and get_constructor_season_results let you pull every race result for a specific driver_id or constructor_id within a season. The constructor variant includes results for both drivers on the team, making it straightforward to compare teammates race by race. Driver identifiers follow a consistent slug format (e.g., hamilton, max_verstappen, leclerc), as do constructor identifiers (red_bull, ferrari, mercedes).
The Ergast API is a managed, monitored endpoint for ergast.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when ergast.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official ergast.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a season-by-season championship tracker using
get_driver_standingsandget_constructor_standingsat each round. - Analyze pit stop strategy patterns across a season using
get_pit_stopsfiltered bystop_number. - Compare teammate qualifying performance lap-by-lap using
get_qualifying_resultsQ1/Q2/Q3 fields. - Reconstruct historical grid-to-finish position deltas using
get_race_resultsacross multiple seasons. - Map every F1 circuit with GPS coordinates using
get_circuit_infoLocation lat/long fields. - Calculate driver career statistics by combining
get_seasons_for_driverwith per-season results fromget_driver_season_results. - Track constructor reliability by counting DNF status codes via
get_finishing_statusfiltered by season and team.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Ergast have an official developer API?+
What does `get_lap_times` return, and does it cover all laps in a race automatically?+
Laps array with a Timings entry per driver for the requested lap. You must pass a specific lap_number; without it the response defaults to a single lap rather than the full race. To get every lap, iterate lap_number from 1 up to the race distance.Does the API cover sprint race results or sprint qualifying formats introduced in recent seasons?+
How far back does the historical data go, and are all fields populated for early seasons?+
Can I get driver or constructor data filtered by both nationality and season simultaneously?+
get_drivers and get_constructors endpoints support filtering by season but do not accept a nationality filter. You can retrieve the season-filtered list and filter by nationality client-side, or fork the API on Parse and revise it to expose nationality as a query parameter.