- 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”
Add any further questions you would like answered here.
The API looks fantastic. I was just wondering, for the coming season, how soon after a round do you expect the data be available via the API?
Admin: Kieren – I’ve added a comment above.
Very cool! I was wondering why the delay for the race results? Are you grabbing the data automatically from the formula1.com website, or are you entering the race data manually into your database?
Hi Vito. The delay has typically been around 2 hrs this season. In the future it will depend when the race starts relative to my local time and whether I am dedicated enough to be awake!
Great work, just a little question regarding client-side access:
Are you considering JSONP as a response format?
Thanks, keep up the good work!
Hi Luke,
I’d consider it, if there’s a demand. Would you use it?
If it was available I would! I wouldn’t add it for me alone, but if others think it a good idea (and you think it would be beneficial) I’d definitely use it over JSON or XML for prototyping.
Would it be acceptable to store any of this information temporarily in a database to reduce hits on the API? A little like Google maps allows with their Geoencoding API?
Hi James,
No problem. You can do what you like with the data as long as any service you provide from it is within the Terms and Conditions.
Chris
I would definitely use JSONP. With JSONP I could build a client-only application for custom statistics, without having to use a proxy to circumvent the cross-domain-policy.
Currently I’m thinking about a “what would the standings be with the old point system” page (or any custom point system).
Ok, I’ve added JSONP support to the Race Schedule call for people to try. If you include a query parameter called “callback” in the URL you’ll get JSONP rather than JSON.
e.g. http://ergast.com/api/f1/2011.json?callback=parseSchedule
Feedback would be appreciated. If people are happy with this approach I’ll add it throughout the API.
Notes:
1. Content-type changes to “application/javascript”
2. Any non-alphanumeric characters are stripped from the callback parameter value.
I’ve now added JSONP support to all the API calls.
The callback parameter value must be a valid Javascript function name otherwise you get a “400 Bad Request” error.
Let me know if you build anything interesting with it.
Hey,
I was wondering if there’s an ordering parameter that can be added to the api query?
Cheers,
James
Hi James,
No – most queries have an obvious ordering for the data so I’ve used that as the default. Let me know if you have a particular requirement in mind.
Chris
This site is great. Would it be possible to add engine manufacturer information as well as constructor? Teams have often switched engine supplier and this is an important factor in their performance. Similarly engine rules era, for example V6 Turbo, V8 and V10. When the engine rules have changed there has frequently been a shake-up which we are now experiencing with the move to the current regulations. This would make a fantastic data source even more useful and complete. Thanks!
Hi Rob,
Good idea. I’ll consider it for next year as I don’t like to make changes to the API mid-season. Is the engine-constructor relationship ever likely to change mid-season?
Cool, thanks for your reply and positivity.
I don’t think a constructor has changed engine supplier mid-season certainly in the last 20 years or so from memory. It may have happened in the early days.
Hello.
Great work with this API!
I have one question, which timezone are you using in the start time of the GP, for example?
Ty.
Hi Paulo,
Thanks for the positive comments. The API uses UTC for the start times, as denoted by the “Z” suffix. If you spot any errors let me know – I don’t always get things right or spot re-scheduling.
Hi,
Was wondering if there is any data around the web or here that denotes when Safety Cars have been deployed during races ?
Hi John,
Not that I’m aware of, unfortunately.
Hi John,
You may query lap times for that. If laptime > laptime*10%(previous lap) => safety car.
Any scope for doing this in real time?
Cheers,
Dom
Hi Dom,
Do you mean real-time lap times? Unfortunately, those aren’t openly published AFAIK.
Hello,
First of all, congratulations on great job! Well done!
I’d like to list all races where a Driver had the fastest race lap.
Can you please help me build a SQL Query that does that?
Thank you
Hi Rogerio,
For a specific season the query would be:
http://ergast.com/api/f1/2013/fastest/1/resultsFor a specific driver the query would be:
http://ergast.com/api/f1/drivers/alonso/fastest/1/resultsYou can also combine the season and driver parameters.
Hope that helps,
Chris
Hello Chris,
I’m using a local database image… can you please help me with a MySQL query?
Thanks!!!
Hi Rogerio,
Ah ok. In the results table the “rank” field is the fastest laps ranking for each race, so filter on rank=’1′ e.g.
SELECTSQL_CALC_FOUND_ROWS
ra.year, ra.round, ra.name, ra.date, ra.time, ra.url,
ci.circuitRef, ci.name, ci.location, ci.country, ci.url, ci.lat, ci.lng, ci.alt,
re.grid, re.positionText, re.positionOrder, re.number, re.points, re.laps, re.time, re.milliseconds, re.rank, re.fastestLap, re.fastestLapTime, re.fastestLapSpeed,
dr.driverRef, dr.number, dr.code, dr.forename, dr.surname, dr.dob, dr.nationality, dr.url,
st.statusId, st.status,
co.constructorRef, co.name, co.nationality, co.url
FROM
races ra, circuits ci, results re, drivers dr, constructors co, status st
WHERE
ra.circuitId=ci.circuitId AND ra.raceId=re.raceId AND re.driverId=dr.driverId AND re.constructorId=co.constructorId AND re.statusId=st.statusId AND dr.driverRef='alonso' AND re.rank='1'
ORDER BY
ra.year, ra.round
Hi Chris,
Excellent!
Thank you very much!!!
Hi,
I would like to ask you guys if does anybody use the API with Ruby on Rails or know how to use it.
I´m trying to do it and I am really stack with it. Im calling the next:
http://ergast.com/api/f1/2014/driverStandings.json
And try to parse it in order to show in my a list, such as:
Drivers Championship Standings
1 Lewis Hamilton Mercedes 384
I have tried many differents way but I cant, I did with angular but unfortunately I need to do just with Rails.
I would realy appreciatte if you can give me a hand.
Thanks
Hi Manuel,
Sorry – I can’t help you with Ruby. Perhaps someone at Rails Forum could help? There’s also a Ruby wrapper for the Ergast API.
Chris
Hi!
This site is fantastic really. The best database for formula one I’ve seen.
Can you please tell me how is it possible to Import these data with Excel? It’s really annoying to do so manually.
Thanks again for this site!
Marco
Hi Marco,
Thanks for the positive comments. There’s some advice on direct import to Excel here:
http://excelramblings.blogspot.co.uk/2012/04/json-data-for-all-f1-races-straight.html
Hi,
first of all, thanks for your dedication to suply us with data :).
I have one question, is there any reason why the “contructors” table does not have a “driverid”?
if posible could you add it to the table?
keep up the good work!
Pheaxx
Hi Pheaxx,
The reason the constructors table doesn’t have a driverId field is to decouple drivers from teams. This is because drivers frequently move between teams – sometimes even mid-season! You can identify the drivers associated with a constructor in a particular year by doing an SQL join between the driver, constructor, races and results tables. That’s what happens if you call this method:
http://ergast.com/api/f1/2015/constructors/ferrari/drivers
Hi,
is it possible to download JSON file?
Thanks
It seems that for example http://ergast.com/api/f1/2016/1 contains only a start time of the actual race. Is there a possibility to get starting times for all practice and qualifying sessions also?
Hi A,
Do you know of a reliable source of the additional start times? Preferably in UTC.
Hi Fox,
Do you mean a JSON file representing the entire database?
Hello, is there any way to retrieve an amount of constructor championships for a driver?
By the way, this is an excellent database! Really glad I’ve found it 🙂
Hi Whiskey,
Unfortunately you can’t do this in one query. One method would be to get all the seasons for a driver e.g.
http://ergast.com/api/f1/drivers/alonso/seasons
Then find the constructors for each season e.g.
http://ergast.com/api/f1/2001/drivers/alonso/constructors
Then check whether they won the championship e.g.
http://ergast.com/api/f1/2001/constructors/minardi/constructorStandings/1
Very useful API. Saves me the time of scraping this stuff myself. Thanks!
Thanks for the positive comments avalon.
Let me know if you build something interesting.
Chris
as always this is best every api… when will the database image be updated for download
Done (sorry – got distracted yesterday)
No worries, wished i could help…… and Thank you:
Hi, thank you for offering this wonderful resource and making it accessible so easily.
My questions are related to the pitstops.
(1) There appear to be two formats for pitstop duration: E.g. 27.831 and 18:09.312.
Is this an error (the times seem to differ quite a lot) and if not, how should I interpret the second format (xx:xx.xxx). These results are derived from: http://ergast.com/api/f1/current/last/pitstops
My second question is: the pitstop times appear to be the period from pitlane entry to pitlane exit. Are they date on the actual ‘stopping’ time also available?
Thanks,
Richard
Hi Richard,
The duration format is: [[[M]M:]S]S.sss (i.e. minutes and the following hyphen are omitted for durations of less than one minute). The long duration in your example was the result of a red flag period.
Unfortunately, the actual stopping time is not made available AFAIK.
Hello, when will the database image be updated for download
Hi James,
Done. I should automate this.
Chris