Ergast Developer API

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

323 responses to “FAQ”

  1. Fabian Avatar
    Fabian

    Hi Chris,

    pretty sure, i checked the code twice and i didn’t file for years. I only filter for statusId’s.
    I can sent you the code as an email if you want (as Markdown or HTML).

  2. Admin Avatar
    Admin

    Hi Fabian,
    But Grosjean did not compete in Formula One in 2021.
    Chris

  3. Fabian Avatar
    Fabian

    Hi Chris,
    my bad, I meant the 2020 accident he had, mixed up the years sorry for that.
    But stillt the last time a driver suffered a injury according to the tables I get was 2011.

  4. Admin Avatar
    Admin

    Hi Fabian,
    No worries. AFAICT a status set to “Injury” usually indicates the driver was unable to start a race due to his state of health e.g. Patrick Tambay in the 1982 Swiss Grand Prix. It is not usually used when the driver suffers an injury during a race due to a collision.
    Cheers,
    Chris

  5. Fabian Avatar
    Fabian

    Hi Chris,

    this explains a lot, I couldn’t find anything on the internet when which statusId is used, do you have any source where I can find it? Let me guess crashes with injury to the driver are only listed as accident am I right?

  6. Admin Avatar
    Admin

    Hi Fabian,
    > Let me guess crashes with injury to the driver are only listed as accident am I right?
    Yes, or “Collision”.
    Cheers,
    Chris

  7. julesg Avatar
    julesg

    Hello, how can I get with python, the race result (only the players and positions) in a text file ?

  8. Albe Avatar
    Albe

    Hi,
    I think Zhou is impossible to find with the command :
    query_driver(driverid = ‘zhou’)

    Thanks

  9. Admin Avatar
    Admin

    Hi Jules,
    There are a couple of Python wrappers for the API listed on the Development Tools page. They would be a good starting point.
    Cheers,
    Chris

  10. Admin Avatar
    Admin

    Hi Albe,
    I don’t recogise the query – what software are you using? The API query is https://ergast.com/api/f1/drivers/zhou and that seems ok.
    Cheers,
    Chris

  11. Andy Avatar
    Andy

    Hi,

    I’m trying to request all race entries for a particular driver: (‘http://ergast.com/api/f1/drivers/{chosen driver}/results’)

    Via the website this works fine, but when I try to make an API request for the data, I can only get the first page of results to play with. Any suggestions?

  12. Admin Avatar
    Admin

    Hi Andy,
    Have you tried using the limit and offset query parameters?
    e.g. https://ergast.com/api/f1/drivers/alonso/results.json?limit=100&offset=100
    Details are on the main documentation page under “Response paging”.
    Cheers,
    Chris

  13. Alejandro Rodriguez Avatar
    Alejandro Rodriguez

    Do you have plans to provide data from practices?

  14. julesg Avatar
    julesg

    Hello,

    I’ve been trying to retrieve data in SwiftUI for several months and I can’t manage to match the structure of the results with my app. Someone can help me it would save my project !

  15. Admin Avatar
    Admin

    Hi Alejandro,
    I’ve never covered practice data because I’m always working on practice days unfortunately.
    Cheers,
    Chris

  16. Admin Avatar
    Admin

    Hi Jules,
    Can you dump JSON data to the console? Paste the results here.
    Chris

  17. Patrick Avatar
    Patrick

    How soon after qualifying is over does this database update? I live in the U.S. and always watch races after they’ve happened, so I’m attempting to create a sort of spoiler free stats page for myself that has info up to qually but no further.

  18. Admin Avatar
    Admin

    Hi Patrick,
    Usually within 2 – 6 hrs, depending on the time zone and my availability.
    Cheers,
    Chris

  19. Luca Avatar
    Luca

    Hello,
    Thanks for these awesome APIs!

    I have 2 questions:
    -I’m trying to get drivers and constructors for 2023, usually when they’re available?
    -Is it possible to have the drivers->constructors association before the start of the race?

    thanks in advance

  20. Admin Avatar
    Admin

    Hi Luca,
    I’ve added provisional drivers and constructors – see here for details: http://ergast.com/mrd/drivers-and-constructors-for-2023/
    Unfortunately, there isn’t an easy way to associate drivers with constructors until after the first race due to the structure of the database (the driver/constructor relationships are established by entries in the results table)
    Cheers,
    Chris

  21. Davide Avatar
    Davide

    Hi, is it possible to integrate this api in an android free app with ads?
    I dont know if is a commercial use.
    Thanks

  22. Admin Avatar
    Admin

    Hi Davide,
    That’s fine – add funded websites are permitted so I guess apps are too – I’ll clarify the Terms & Conditions.
    Cheers,
    Chris

  23. Kimbo Avatar
    Kimbo

    Does anyone know where i can see the specific driverIds? Seems to be the last name, however in case of “Mick Schumacher” i dont get a result.

  24. Admin Avatar
    Admin

    Hi Kimbo,
    One way to find driver IDs is to make a query using the Query Database page. For Mick Schumacher the ID is: mick_schumacher
    Cheers,
    Chris

  25. ixtrunai Avatar
    ixtrunai

    Hi, I´m not sure if time schedules for 2023 calendar are OK.

    Checking with the official F1 site, seems to be different.
    https://www.formula1.com/en/racing/2023/Bahrain.html

  26. Admin Avatar
    Admin

    Hi ixtrunai,
    Thanks for the warning. I updated the schedule but further changes may be required in the future as the official schedule is often amended.
    Cheers,
    Chris

  27. eug8 Avatar
    eug8

    Hello,

    just curious, what is the source of truth of the ergast data?

    Cheers,
    Eug8.

  28. Admin Avatar
    Admin

    Hi Eug8,
    Historical data came from helpful contributors and sites such as Wikipedia. More recent data comes from wherever I can find it at the time.
    Cheers,
    Chris

  29. Cyril Avatar
    Cyril

    Hello Chris,

    I really like the Laps timetable. I did not check during the last grand-prix but was it updated in some sort of real-time during the race?
    I doubt but just asking. If so, what would be the best call to get current race leaders?

    Or maybe it’s just not doable with Ergast API.

    Thanks again for all this data, really appreciated it, just donated!
    Cheers,
    Cyril

  30. Andrew Avatar
    Andrew

    Hello Chris,

    I am building an API and need to know every track that has ever been raced on. Is there a way I can see all the circuit ids? The only one I know right now is Monza.

    To sum it up I need to know all the circuit ids.

    Thanks,
    Andrew

  31. Savannah Avatar
    Savannah

    @Andrew, you should be able to find all the IDs and tags on the database images page: http://ergast.com/mrd/db/. I downloaded the CSV files and they’re all available in there.

    Thanks for your work on this API!

  32. Admin Avatar
    Admin

    Hi Cyril,
    Unfortunately the API does not provide live data. All the lap data is usually uploaded 2-6 hours after the race.
    Cheers,
    Chris

  33. Admin Avatar
    Admin

    Hi Andrew,
    You can see them all listed here: https://ergast.com/api/f1/circuits.json?limit=100
    Cheers,
    Chris

  34. Rogier Avatar
    Rogier

    Just to keep me from searching; the starting grid isn’t stored in the database right?
    I think there is probably some mismatch between qualy result and starting grid as a result of regulations. Is that correct?

  35. William Avatar
    William

    Does the data update 2-6 hours after qualifying AND after the race, or just 2-6 hours after the final race everything is updated?

  36. Cyril Avatar
    Cyril

    Hello, just to let you know that a new week end format is being tested this at Baku, with:

    Friday:
    – FP1
    – Race Qualification

    Saturday:
    – Sprint Qualification
    – Sprint Race

    Sunday:
    – Race

    We do not know yet if it’s just a one-time testing or will be like this everytime.
    Would it be possible to update the API accordingly?
    Thank you so much.

  37. Admin Avatar
    Admin

    Hi William,
    It’s usually within 2-6 hours of the race, sprint or qualifying session. I’ve added a note to the FAQ.
    Cheers,
    Chris

  38. Admin Avatar
    Admin

    Hi Cyril,
    Not sure I can do anything about this in the near future. Let’s see whether they stick with it.
    Cheers,
    Chris

  39. Andrew Avatar
    Andrew

    Hi! Could you help me please? Is there a way to make only one request for getting information of values drivers points on every race? I can get this info getting one request for every race increasing race number on this endpoint: f1/2023/1/driverStandings, but maybe I can make only one request for this? Thank you!

  40. Cyril Avatar
    Cyril

    Hi Chris,

    The P1 and P2 start times at Miami this weekend are 30mins too late on the API.
    The rest is correct!

    On a side note: is there a way for you to add another admin able to do such modifications to the database more quickly if you are not available? In order to help you maintain the project. Ideally, someone who is donating would make more sense.

    A second person could also help with results and stuff.
    Did you ever think about this?

    Cheers,
    Cyril

  41. Admin Avatar
    Admin

    Hi Andrew,
    You can get the results for every race in one query and do you own totals with:
    https://ergast.com/api/f1/2023/results?limit=1000
    Cheers,
    Chris

  42. Admin Avatar
    Admin

    Hi Cyril,
    Thanks – now corrected.
    I’d like to make the admin multi-user but it’s not practical with the current code. Also I’d have to learn to trust people!
    Chris

  43. Alex Avatar
    Alex

    Hi,
    Firstly, thanks for maintaining this API. Are there any plans in future to add more data for circuits? For example, the number of corners, single lap distance, full race distance etc
    Alex

  44. Admin Avatar
    Admin

    Hi Alex,
    No, there aren’t any plans. Circuit configurations change fairly frequently and currently there’s no way to support time-dependent features for circuits in the database.
    Cheers,
    Chris

  45. Jesus Avatar
    Jesus

    Hey, Is there an endpoint to filter pilots between two dates? (from, to)
    Thanks for all the work in this API 😀

  46. Admin Avatar
    Admin

    Hi Jesus,
    Unfortunately not.
    Cheers,
    Chris

  47. Barvoziker Avatar
    Barvoziker

    Hi ! I use an image of database and I want to take the list of drivers and his point this year i have that but i have a bug :
    Thanks for help 🙂

    SELECT DISTINCT ds.position, d.forename, d.surname, ds.points
    FROM “driverStandings” ds
    JOIN drivers d ON ds.”driverId” = d.”driverId”
    JOIN races r ON ds.”raceId” = r.”raceId”
    WHERE r.year = 2023
    GROUP BY ds.”driverId”, ds.position, d.forename, d.surname, ds.points
    HAVING ds.points = (
    SELECT MAX(points)
    FROM “driverStandings”
    WHERE “driverId” = ds.”driverId”
    AND “raceId” IN (
    SELECT “raceId”
    FROM races
    WHERE year = 2023
    )
    )
    ORDER BY ds.points DESC
    –LIMIT 20;

  48. Cristian Avatar
    Cristian

    Hello,

    I am currently working on a website application based on Ergast API, I’ll have database locally, and fetching occasionally, to avoid reaching limit with API calls.
    From Terms and conditions I see that running ads on website is allowed, but I would like to ask if it is permissible to include a donation page on website. Would this be allowed under the terms of use?

    Thanks in advance!

  49. Admin Avatar
    Admin

    Hi Cristian,
    That’s fine – it’s not a commercial activity.
    Cheers,
    Chris

  50. Vishnu Avatar
    Vishnu

    Do you any information related to safety car deployment? eg: given the year and track, was the SC/VSC deployed?

Older Comments
1 … 4 5 6 7
Newer Comments

Leave a Reply

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