FAQ

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

342 responses to “FAQ”

  1. James Murrell Avatar
    James Murrell

    Big Thanks….

  2. Bas Avatar

    Hey there Chris,

    first of all thanks for supplying and maintaining this API. I’m using it (for educational purposes) as an example in workshops on testing RESTful APIs and was wondering if there is any way to run the whole API locally (inside a VM or a Docker image for example) to prevent any issues with the API being temporarily unavailable at the time of my workshops..

    Thanks in advance for your answer and keep up the good work!

    — Bas

  3. Admin Avatar
    Admin

    Hi Bas,
    Unfortunately there’s currently no way to do this – but it’s a nice idea. I’ll think through the implications of releasing the server code – maybe someone would add the cloud support? On the plus side the API is usually pretty reliable.

  4. Bas Avatar

    Hi Chris,

    thanks. The reason I asked is (of course) because I ran into this situation before.. I’ll find a suitable way of dealing with this though, no worries. Maybe recording traffic through a proxy and using that to generate stubs.

  5. Robert Avatar

    Hi,

    I like your API a lot. Tester and wrote scripts to test data and making imports to a Joomla component. I want update the qualifying results and race results. Is the qualifying data coming the same day as the race results?

    Or do they come the same day as the qualification rounds end?

    Robert

  6. Robert Avatar

    When are qualifying results become available? Is this after the race or when qualifying results are present? (Last qualifying date)

    Thanks for the great API!!

  7. Robert Avatar

    Sorry for the double post, I had the wrong ordering and did not saw my first post..

  8. Admin Avatar
    Admin

    Hi Robert,
    Thanks for the positive comments. Qualifying results are usually available a couple of hours after the qualifying session ends.

  9. Rob I Avatar
    Rob I

    Is there any way, either now or in the forseeable future, to get sector time data in addition to laptime data? Either way, love the work you’ve done here. I was hoping to implement a ‘live’ laptime dashboard for people like me who watch the races on ‘tape delay’ or people watching old races and whom would still love a live timing screen. I’ve worked out a simple method for users to start the ‘live’ timing and the race video at the same time so that everything will ‘sync’; but I was curious if sector times were available somehow I’m missing or if that data just isn’t there. Either way I intend to complete the project because even with just whole laptimes I think there’s a lot of value. Thanks for your hard work!

  10. Admin Avatar
    Admin

    Hi Rob,

    Unfortunately not. I’m not sure there’s a source.

  11. Nag Avatar
    Nag

    Hi,

    This is a great resource, and I’m thinking of building an app that uses this API. It’ll be on iOS, and it will be personal (my wife and I will use it, not on the App Store).

    Do you see this project continuing into 2018 and beyond? I’m only a hobby programmer, so I don’t want to spend a lot of time if this API is scheduled to be deprecated soon. Also my wife won’t be happy if her app stops working..

  12. Admin Avatar
    Admin

    Hi Nag,

    Yes, the API will continue, at least for the next few years.

  13. Nag Avatar
    Nag

    Thank you for the response.

  14. Victor Avatar
    Victor

    Hi,

    This is an interesting API, I am an iOS developer and I would like to develop a statistics application for my own use, I have worked with Restfull API and in all of them “always” there is an authentication system except this one. You need to have a control over who is consulting your API, you have to protect yourself from malicious developers. Please, to solve this, read a bit of OAuth2 or similar. I hope this is useful for you. Sorry for my bad English, I speak Spanish ๐Ÿ™‚

  15. tob Avatar
    tob

    Hi,

    great API so far. For my App I would like to get the date and time of the F1 qualifying which isn’t stored yet. The problem is that the qualifiying isn’t always 24h before the race. Is it possible to get that additional data?

  16. Admin Avatar
    Admin

    Hi Tob,
    Unfortunately, it’s quite hard to find this info before the season starts so I haven’t included it in the schema. Do you know of a reliable source?
    Chris

  17. tob Avatar
    tob

    Hi Chris,

    thank you for your fast response. I think http://www.f1calendar.com is a reliable source for that, but I don’t know how fast they update their data for a new season. But maybe you can have a look on that website.

  18. Kamil Avatar

    Great API, thanks for your work on it… Just a quick question – is there any problem with this week data? I am trying to get qualification data, but it still looks empty. Is there any problem or API change? Thanks, Kamil

  19. Brad Avatar

    Hi Chris, I hope all is well. Is there an estimate on the Spa data update? My wife and I very much enjoy your efforts and use the data as F1 fans to enhance our PHP and MySQL skills.

    Best
    -Brad & Karen

  20. Admin Avatar
    Admin

    Hi Kamil, Brad,
    Sorry for the delay – there have been a number of technical issues this weekend. The qualifying data is now available and a MySQL dump (without lap times as these still need to be fixed)
    Chris

  21. Vivec Avatar
    Vivec

    Hi Chris,

    Just wanted to say thank you for this great resource.
    Developing a nice dashboard for this data. Hobby project :).

    I’m now trying to find resources for:
    – tyres (and usage per lap)
    – engine manufacturers (linked to constructor and results)
    – perhaps even engine (type) usage
    – penalties
    – weather per event

    It’s incredibly hard to find comprehensable resources.
    Wikipedia holds a lot of data, but almost never in a fixed structure (for scraping)…

  22. Rick van Bork Avatar
    Rick van Bork

    Hi,

    I’m currently using the API for educational purposes and loving it so far!
    However, I noticed that the following query:
    http://ergast.com/api/f1/2015/circuits/suzuka/results/1.json
    misses the โ€œTimeโ€ key, which keys the โ€œmillisโ€ and โ€œtimeโ€. Suzuka 2015 is the only race of all races in F1 history to not include this race data.

    A very minor glitch and easy to manually fix for my project, but I thought to notify you anyways ๐Ÿ™‚

    Thanks for your hard work maintaining the API for motorsport fans and hobbyist like me!

    Rick van Bork

  23. Admin Avatar
    Admin

    Hi Rick,
    Thanks for the warning – I’ll add the missing data.
    Chris

  24. vijay bhaskar Avatar
    vijay bhaskar

    Hi,
    I have been using this api for my project to display the ferrari statistics..If you provide the cars used by the racers then it would be extremely helpful to me

  25. Admin Avatar
    Admin

    Hi Vijay,
    Sorry – the database doesn’t have that data,
    Chris

  26. Anon Avatar
    Anon

    Hi,

    I’m currently building a small Angular app using this Api, loving how easy it is to use and how much is in there btw!

    I was wondering if there was a way to retrieve the total number of race wins a driver/team has as well as how many championships a driver/team has?

    Thanks

  27. Admin Avatar
    Admin

    Hi Anon,
    To get the total number of race wins for a driver use, for example:

    http://ergast.com/api/f1/drivers/alonso/results/1

    or for a constructor:

    http://ergast.com/api/f1/constructors/renault/results/1

    and use the value of the “total” attribute in the responses.
    Good luck with your app.
    Chris

  28. Raphael Avatar
    Raphael

    Hello,
    Amazing API that you have here.
    I would like to know if its possible to get a json with a limit bigger than 30.
    Many Thanks!

  29. Admin Avatar
    Admin

    Hi Raphael,
    Yes, you can increase the limit – see here: http://ergast.com/mrd/#paging

    However, please use the smallest limit value you can: it’s much easier for the server to provide a number of short responses rather than one large one – and you’ll get faster results.
    Chris

  30. Mark Avatar
    Mark

    Hi,

    Firstly, thanks for making this data freely available. It’s saved me a lot of time.

    I’m creating a Xamarin app for use by friends using the data provided by your API. The purpose of the app is a kind of league, where before the start of the season we all get to choose 2 drivers, and at the end of the season the person with the most points is bought a trophy by the others.

    What I’d like to be able to do is, before the season starts, is to get a list of drivers and the constructor they’re driving for. Unless I’m missing something, I can’t find a URL I can call to give me this data. Is this possible?

    Thanks in advance,

    Mark

  31. Admin Avatar
    Admin

    Hi Mark,
    You’re right – it’s a limitation of the current design of the API. The association between drivers and constructors is established by the race results – so you need the results from the first race to get this. It’s a difficult issue to fix because the team announcements trickle in one-by-one and may not be finalised until a week or two before the first race – and sometimes drivers or teams don’t turn up on race day (remember USF1?). I’ll try to think of a solution for the next season but it will probably have to be manually edited and always provisional.
    Chris

  32. Umang Avatar
    Umang

    Hello,

    I will get the list of the winners for every race for the selected year on this API but i couldn’t find the winner has been the world champion in the same season.

    Currently i am referring this api http://ergast.com/api/f1/2008/results/1.json?callback=JSON_CALLBACK

    So can you let me know which API i can find both value which i required??

  33. Clayton Avatar
    Clayton

    Hi

    Thank you for the great APi, I wanted to find out if there is a way to get driver/constructor champions for a specified period?

    e.g. Get all constructor champions between 2013 and 2018

  34. Admin Avatar
    Admin

    Hi Clayton,
    You will need to make a standings query for each year e.g. http://ergast.com/api/f1/2013/constructorStandings/1
    More details here: http://ergast.com/mrd/methods/standings/
    Multiple queries with small responses are actually easier for the API, memory wise.
    Chris

  35. Giacomo Avatar

    Hey, great Api, congratulations!

    The only issue I have is the missing timezone markers. From what I understand, you return the race starting time as UTC, but the PitStop times as local time. For example, race 2018-1 (Mexico) is described as starting at 19:10, but the first pitstop (on the first lap) is marked as 13:14, which makes sense since Mexico is UTC-6, but… it would be nice if you could tag them as such (13:14:12-0600), or just have it all in UTC, or simply mention it in documentation to remove any doubt ๐Ÿ™‚

    Thanks for the great work!

  36. Admin Avatar
    Admin

    Hi Giacomo,
    That’s good point – all the times should be UTC.
    Chris

  37. Kieran Avatar
    Kieran

    Hi,

    It looks like the security certificate has expired within the last few days. Is it going to be renewed?

  38. Admin Avatar
    Admin

    Hi Kieran,
    Apologies – there’s a cron script which is meant to renew this but it failed. I’ve done it manually.
    Thanks for the warning.
    Chris

  39. Calvin Avatar
    Calvin

    Hi,

    Firstly, how would I be able to get this query in MySql:
    http://ergast.com/api/f1/constructors/renault/constructorStandings?

    And second, if I was to use the MySql dump from races 1950-2018, would caching the API for updates for 2019 and onwards be a good idea?

    Thanks.

  40. Admin Avatar
    Admin

    Hi Calvin:
    The query:
    http://ergast.com/api/f1/constructors/renault/constructorStandings

    would be implemented as:
    SELECT c.constructorRef, c.name, c.nationality, c.url, cs.points, cs.position, cs.positionText, cs.wins, r.year, r.round

    FROM constructors c, constructorStandings cs, races r
    WHERE cs.raceId=r.raceId AND cs.constructorId=c.constructorId AND c.constructorRef='renault'
    AND (r.year, r.round) IN (SELECT year, MAX(round) FROM races GROUP BY year)
    ORDER BY r.year, cs.position LIMIT $offset, $limit

    Re: caching – you only really need to cache the queries you expect your users to request regularly. This will improve the performance for them as well as everyone else. Make the cache lossy, with something like a 5 minute lifetime.

    Chris

  41. Calvin Avatar
    Calvin

    Hi Admin once again,

    Is there a way to get the gaps between the drivers say:
    on lap 32 of the 2018 Australian GP?

    Thanks.

  42. Admin Avatar
    Admin

    Hi Calvin,
    You would have to aggregate the individual lap times for each driver up to lap 32.
    Chris

  43. Xavier Montasell Avatar
    Xavier Montasell

    Hi,
    how can i get the json response ?

  44. Admin Avatar
    Admin

    Hi Xavier.
    JSON is obtained by appending “.json” to URLs e.g.
    http://ergast.com/api/f1/current/last/results.json
    For more details see the “Response formats” section on the homepage.
    Chris

  45. Vincent Avatar
    Vincent

    Hi there,

    Love your website. Thanks so much for providing this wealth of information for free. I’d like to ask – and you’re more than welcome to not give away your secrets – but how do you get this data, and how do you afford to provide it for free?

    Thanks,
    Vince

  46. Admin Avatar
    Admin

    Hi Vincent,
    Thanks for the positive comments. All the data comes from public sources and it doesn’t cost much to run a server these days. The only real cost is the time required to collate and check the data.
    Cheers,
    Chris

  47. Vincent Avatar
    Vincent

    Hi Chris,

    Is there a page on your site that explains what the columns mean? e.g. Right now I’m looking for the definitions of positionText and positionOrder in ‘results’.

    Thanks!
    Vincent

  48. Admin Avatar
    Admin

    Hi Vincent,
    There’s an explanation of the position and positionText fields on the Results page.

    – The position is always an integer and is the official finishing position. Not all drivers get one.
    – The positionText field can be an integer but can also be a finishing status e.g. "R" for retired.
    – The positionOrder field is an integer you can use to order the results – it’s like the position field but all drivers get one.

    Hope that helps.
    Chris

  49. Tom Avatar
    Tom

    Hi,

    Thanks for providing this API, it’s been great to learn how to fetch data that I’m really interested in.

    I’m currently trying to get all race results for the current season so far (specifically starting grid and finishing position data) by using http://ergast.com/api/f1/current/results.json. This only has been returning the first two rounds however. Am I requesting the wrong endpoint? Thanks!

  50. Tom Avatar
    Tom

    Hello again, lesson learnt – I hadn’t realised there was a default limit of 30 results!

Leave a Reply

Your email address will not be published. Required fields are marked *