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?

Usually in 2 – 6 hrs.

194 Responses to “FAQ”

  1. Admin says:

    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 says:

    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 says:

    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 says:

    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 says:

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

  6. Admin says:

    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 says:

    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 says:

    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 says:

    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 says:

    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 says:

    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 says:

    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 says:

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

  14. Tijmen says:

    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 says:

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

  16. Admin says:

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

  17. Andrew says:

    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 says:

    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 says:

    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 says:

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

  21. Mihai says:

    Hi,

    Pitstop data is missing for the Spanish gp 2021

    Many thanks

  22. Admin says:

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

  23. Gus says:

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

  24. Mihai says:

    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 says:

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

  26. Admin says:

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

  27. Yurii says:

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

  28. Konstantin says:

    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 says:

    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 says:

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

  31. Admin says:

    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 says:

    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 says:

    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 says:

    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 says:

    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 says:

    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 says:

    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 says:

    Hi Robertino,
    You need to change:

    teams: response.data

    To the following:

    teams: response.data.MRData.ConstructorTable.Constructors

    Cheers,
    Chris

  39. Gus says:

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

  40. Admin says:

    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 says:

    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 says:

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

  43. Admin says:

    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

Add a Comment: