- How do the current, last and next shortcuts behave?
- Is there any restriction on how qualifiers can be combined?
- What happens if a round is not specified?
- What is the purpose of the attributes in the table elements?
- How soon after a race will data become available?
Ask additional questions using the comments box.
How do the current, last and next shortcuts behave?
For the purposes of the API, a season is assumed to begin when results become available for the first race of the season. This transition will be seen if the <season> field in URLs is set to “current”.
In a similar way, the changeover point for the “last” and “next” round shortcuts occurs when a new set of race results become available. After the last race of a season the URL:
http://ergast.com/current/next/...
will refer to the first race of the following season.
Is there any restriction on how qualifiers can be combined?
A query can include any combination of the following qualifiers unless otherwise stated:
/circuits/<circuitId>
/constructors/<constructorId>
/drivers/<driverId>
/grid/<position>
/results/<position>
/fastest/<rank>
/status/<statusId>
For example:
/drivers/alonso/constructors/renault/results/1
The order of the qualifiers has no effect except that the last one determines the result type.
Season, Driver, Constructor and Standings queries can include the following qualifiers, subject to certain restrictions:
/constructorStandings/<position>
/driverStandings/<position>
The last qualifier in a query determines the type of data returned.
What happens if a round is not specified?
For Standings queries and queries which include a standings qualifier the round value defaults to the last round of each season (i.e. the final standings). Otherwise a query covers all rounds of a season.
What is the purpose of the attributes in the table elements?
All responses contain a table of some kind. The attributes of the table element define the scope of the table and reproduce the criteria specified in the original query. If a specific attribute is omitted the scope concerns all entities of that type e.g. if there is no driverId attribute the scope of the table is all drivers who match the specified criteria.
How soon after a race will data become available?
Data is usually available 2 – 6 hours after the race, sprint or qualifying session.
Comments
344 responses to “FAQ”
Hi John,
Information about the structure of the database can be found on the Database Images page, including an Entity Relation Diagram.
Cheers,
Chris
Hello Admin,
I have a little question,
When will the database will be updated ?
Because I need the driver’s name for the beginning of the 2021 season
thanks !
Hi Morgan,
See: http://ergast.com/mrd/provisional-2021-drivers-and-constructors/
Chris
Hi,
first of all thanks for this API.
I’d like to use your API for a small site for personal usage for me and some friends. My question is about this:
“You must not create any application which polls the API more than four times per second or more than 200 times per hour.”
Can you please give me some more details about it.
– how do you identify the source: by IP or by the origin in the header?
– 4/sec and 200/h is for the whole API or by endpoints like race schedule and standings count separately?
Thanks,
Zoltan
Hi Zoltan,
> how do you identify the source
It’s per client, so each of your users can poll within these limits.
> 4/sec and 200/h is for the whole API or by endpoints
It’s the whole API
I know the limits are annoying but people with a popular app can easily create unintentional DoS attacks – and this has happened!
Chris
Hi. Is there a way to select drivers of a specific year?
Hi Edgar,
If you want a list of drivers from a specific year use:
http://ergast.com/api/f1/<year>/drivers
For example:
http://ergast.com/api/f1/2021/drivers
Chris
Hi Chris,
first, thank you for the time and effort you put into this API, it’s truly great.
I read the terms and conditions and I was wondering if I can use it in an app that is free, and have a donate button in it or have a pro version of the app that allows access to another API for live scores but that doesn’t restrict or use data from you API ?
Thanks!
Hi Clement,
You’re welcome to use the API in a free version of an app – but not in a commercial version.
Cheers,
Chris
Hi Chris,
Are you guys planning on adding more historical data to the qualifying results? I see it is currently only going back to 1994. Would love to have access to data from 1950 onwards as I’m planning on building a free to use website that will show driver records vs their teammates in regard to qualifying, race results.
Please le tme know. Thank you!
Hi Alwyn,
I’d be happy to add more, if someone provides the data in SQL or another machine-readable form.
Cheers,
Chris
Hi. I want to ask about your database. For example, I want to get driver standings(driver’s name and constructor) of a specific year? How can I do this in SQL?
Hi John,
You can see the SQL queries used by the Driver Standings API here:
https://github.com/jcnewell/ergast-f1-api/blob/master/webroot/php/api/DriverStandings.inc
You can compare this against the database table details here: http://ergast.com/docs/f1db_user_guide.txt
Let me know if you need more details via admin@ergast.com
Cheers,
Chris
Hi,
Is there any way to know on which laps the safety car was on track ?
Hi, first of all, I would like to say that this looks like a great API. I was wondering if there is any way of knowing whether it rained during the race.
Kind regards,
Tijmen
Hi Alistair,
No, there’s no explicit signaling for the safety car.
Chris
Hi Tijmen,
No, there’s no data about the rain.
Chris
Hi, thanks for making this available, I was keen to know if it is possible to get what tyre type they were running for a specific lap? Cheers
Hi Andrew,
Unfortunately I don’t have a reliable source of tyre information, so haven’t been able to support this.
Cheers,
Chris
Hi,
Do you have or are able to get data about the teams current engine parts used during the season e.g. how many MSU’s used out of available etc?
Many thanks
Hi Gus,
Unfortunately not. It would be very interesting.
Cheers,
Chris
Hi,
Pitstop data is missing for the Spanish gp 2021
Many thanks
Hi Mihai,
I’ve been unable to obtain it – but still trying.
Chris
Where do you get all your live data from?
Many thanks
Hi,
Pitstop information is available here: https://www.fia.com/events/fia-formula-one-world-championship/season-2021/spanish-grand-prix/race-classification
I don’t know if this helps you but ¯\_(?)_/¯
Hi Gus,
Unfortunately, the API doesn’t support any live data.
Chris
Hi Mihai,
Thanks – the pit stop data is available now.
Chris
Hi Admin. I’m curious where are you getting all this data?
Hi Chris,
Seems like some of the fastest laps are not in the results records. For example, counting race results with rank = 1 gives 22 for Alonso instead of 23 and the only fastest lap that’s missing is 2003 Canadian GP. Looks like rank value doesn’t exist for races prior to 2004. Is there any fix for that?
And thank you for the data, it’s just great!
Hey!
Thanks for the amazing API. Is there a way to see a drivers results for a specific season? For example, if I want to see Norris’ results from his 2020 season, including total points, highest finish, fastest laps, etc?
Thanks,
Jay
Hi Yurii,
The data has come from various sources and contributors – basically wherever I can find it.
Chris
Hi Konstantin,
If you check the documentation for the results query the fastest lap times are included from the 2004 season onwards. If someone can supply the earlier data I would be happy to add it.
Chris
Hi Jay,
You can get all the data with two queries but you’ll have to so some analysis:
http://ergast.com/api/f1/2020/drivers/norris/results.json
http://ergast.com/api/f1/2020/drivers/norris/driverstandings.json
Cheers,
Chris
Hi Chris,
Is there any delay between when the API and the images get updated? Do the images get updated between quali and the race also, or just the API?
Truly appreciate your work on this resource!!!
Regards,
Luke
Hi Luke,
The DB images are updated as soon as all the data for the race has been entered. This is usually 2-6 hours after the race but recently the pit stop data has been hard to obtain so they’ve been updated later. In future I plan to publish them earlier with this data missing and update them when it finally arrives. I don’t publish them after qualifying.
Cheers,
Chris
Hey,
Just a simple question. What is the ‘grid’ value? If we look at the results for Perez in 2021, round 1 (or entry 0) has a grid value of ‘0’. I thought grid would mean starting position, but am I understand ing this wrong?
https://ergast.com/api/f1/2021/drivers/perez/results.json
Thanks.
Hi Jay,
It’s the starting grid position – see the results query documentation for details. A grid value of 0 is used for drivers starting from the pit lane.
Cheers,
Chris
Hi, I am having an error that i cant resolve.
I am doing this:
and I get this from browser:
I have already tried that method with another API and it works but I cant make it with this one.
I think is something about the response i am getting.
Hi Robertino,
You need to change:
To the following:
Cheers,
Chris
Hi, where do you get all the data from?
Thanks
Hi Gus,
Historical data was obtained from Wikipedia and external contributors. Contemporary data comes from a variety of public sources. I use a PHP management interface which allows you to paste/import/check/edit data. It’s beginning to show it’s age…
Chris
Hey,
That’s cool – which public data sources do you use for current season data. Just Interested in seeing what other data is around.
Cool work though!
Hi
I just wanted to ask who’s the creator or devloper of ergas. And thnk you
Hi Radhwane,
The origin of the Ergast API is a mystery, although some say it was created by developers working from a cave called “Eau Rouge” found deep in the Ardennes, having got lost on their way home from the Grand Prix at Spa-Francorchamps.
Cheers,
Chris
Hi Admin,
I am not sure if my last question was posted. Once again thank you for the amazing service.
I am looking for an API that returns number of laps in each circuit. I am not sure if that information is available?
Thanks
Tanzeem
Hi Tanzeem,
The closest the API gets to that is the number of laps completed by the winning driver – which is provided in the results response e.g. https://ergast.com/api/f1/2021/9/results/1.json
I can’t add the true number to the circuit information because it may change over time – and the database structure doesn’t support that.
Cheers,
Chris
Hi Admin,
I was wondering how you will be handling sprint races results? Will you be including them into the service?
Thank you so much for this great service!
Cheers,
Mahshad
Hi Mahshad,
I will be adding the sprint points to the race points in the results table but not modifying the API this season. If the sprint races continue next season I will probably add a new table.
Cheers,
Chris
Hi Admin
First of all, thank you for this amazing API.
I have one question. I am trying to query the database without performing GET requests continuously and reading it into dataframes (this is time consuming if this data is being displayed on the web even though I have used multithreading), in python.
How does one query the database directly? I have looked at your previous comments and went to the github page. Seeing that, I have downloaded Apache because I think I need to “configure an API server independently”. Is there any technical article you could refer me to, to do this if it is even possible?
Thanks again,
Suvashan
Hi Suvashan,
You could load the data from the CSV files available here: http://ergast.com/mrd/db/
Alternatively, you could run MySQL 5.7, load the database image and make SQL queries.
Cheers,
Chris