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

344 responses to “FAQ”

  1. Admin Avatar
    Admin

    Hi John,
    Information about the structure of the database can be found on the Database Images page, including an Entity Relation Diagram.
    Cheers,
    Chris

  2. Morgan Badet Avatar
    Morgan Badet

    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 !

  3. Zoltan Avatar
    Zoltan

    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

  4. Admin Avatar
    Admin

    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

  5. Edgar Avatar
    Edgar

    Hi. Is there a way to select drivers of a specific year?

  6. Admin Avatar
    Admin

    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

  7. Clement Avatar
    Clement

    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!

  8. Admin Avatar
    Admin

    Hi Clement,
    You’re welcome to use the API in a free version of an app – but not in a commercial version.
    Cheers,
    Chris

  9. Alwyn Avatar
    Alwyn

    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!

  10. Admin Avatar
    Admin

    Hi Alwyn,
    I’d be happy to add more, if someone provides the data in SQL or another machine-readable form.
    Cheers,
    Chris

  11. John Avatar
    John

    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?

  12. Admin Avatar
    Admin

    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

  13. Alistair Avatar
    Alistair

    Hi,
    Is there any way to know on which laps the safety car was on track ?

  14. Tijmen Avatar
    Tijmen

    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

  15. Admin Avatar
    Admin

    Hi Alistair,
    No, there’s no explicit signaling for the safety car.
    Chris

  16. Admin Avatar
    Admin

    Hi Tijmen,
    No, there’s no data about the rain.
    Chris

  17. Andrew Avatar
    Andrew

    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

  18. Admin Avatar
    Admin

    Hi Andrew,
    Unfortunately I don’t have a reliable source of tyre information, so haven’t been able to support this.
    Cheers,
    Chris

  19. Gus Avatar
    Gus

    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

  20. Admin Avatar
    Admin

    Hi Gus,
    Unfortunately not. It would be very interesting.
    Cheers,
    Chris

  21. Mihai Avatar
    Mihai

    Hi,

    Pitstop data is missing for the Spanish gp 2021

    Many thanks

  22. Admin Avatar
    Admin

    Hi Mihai,
    I’ve been unable to obtain it – but still trying.
    Chris

  23. Gus Avatar
    Gus

    Where do you get all your live data from?
    Many thanks

  24. Mihai Avatar
    Mihai

    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 ¯\_(?)_/¯

  25. Admin Avatar
    Admin

    Hi Gus,
    Unfortunately, the API doesn’t support any live data.
    Chris

  26. Admin Avatar
    Admin

    Hi Mihai,
    Thanks – the pit stop data is available now.
    Chris

  27. Yurii Avatar
    Yurii

    Hi Admin. I’m curious where are you getting all this data?

  28. Konstantin Avatar
    Konstantin

    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!

  29. Jay Avatar
    Jay

    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

  30. Admin Avatar
    Admin

    Hi Yurii,
    The data has come from various sources and contributors – basically wherever I can find it.
    Chris

  31. Admin Avatar
    Admin

    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

  32. Admin Avatar
    Admin

    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

  33. Luke Avatar
    Luke

    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

  34. Admin Avatar
    Admin

    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

  35. Jay Avatar
    Jay

    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.

  36. Admin Avatar
    Admin

    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

  37. Robertino Avatar
    Robertino

    Hi, I am having an error that i cant resolve.

    I am doing this:

    componentDidMount(){
        axios.get(‘https://ergast.com/api/f1/constructors.json’)
        .then(response =>
            this.setState({
                teams: response.data
            })
        )
    }

    and I get this from browser:

    TypeError: teams.map is not a function.

    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.

  38. Admin Avatar
    Admin

    Hi Robertino,
    You need to change:

    teams: response.data

    To the following:

    teams: response.data.MRData.ConstructorTable.Constructors

    Cheers,
    Chris

  39. Gus Avatar
    Gus

    Hi, where do you get all the data from?
    Thanks

  40. Admin Avatar
    Admin

    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

  41. Gus Avatar
    Gus

    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!

  42. Radhwane Avatar
    Radhwane

    Hi
    I just wanted to ask who’s the creator or devloper of ergas. And thnk you

  43. Admin Avatar
    Admin

    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

  44. Tanzeem Ahmed Avatar
    Tanzeem Ahmed

    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

  45. Admin Avatar
    Admin

    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

  46. Mahshad Avatar
    Mahshad

    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

  47. Admin Avatar
    Admin

    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

  48. Suvashan Avatar
    Suvashan

    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

  49. Admin Avatar
    Admin

    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