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. anon Avatar
    anon

    Hey,

    Is it possible to get the total amount of points for a driver/constructor?

    Thanks

  2. Anon 2 Avatar
    Anon 2

    It is possible to rise the limit of 30 results? Thanks!

  3. Admin Avatar
    Admin

    Yes, you can add a limit field to queries with a value up to 1000 e.g.
    http://ergast.com/api/f1/drivers?limit=100
    Use the smallest value possible for good performance.

  4. Admin Avatar
    Admin

    It is possible to get all the points in one query but it’s slow and you need to add up the points for each year in the results e.g.
    http://ergast.com/api/f1/drivers/alonso/driverStandings

  5. John Doe Avatar
    John Doe

    The time for Vietnam Grand Prix is wrong. Also you can constantly check the time and date for other Grand Prix because COVID virus can cause some changes in the times.

  6. Admin Avatar
    Admin

    Hi John,
    I’ve updated the calendar to reflect decisions. I’ll watch for further changes but if you spot anything let me know.
    Thanks,
    Chris

  7. Brendan Wall Avatar
    Brendan Wall

    HI,
    I am trying to use the api to get a JSON response but keep getting XML how can i specify to get a JSON response?
    Thanks

  8. Admin Avatar
    Admin

    Hi Brendan,
    JSON is obtained by appending “.json” to the URLs e.g.

    http://ergast.com/api/f1/current/last/results.json

    For more information see the Response formats section here:

    http://ergast.com/mrd/

    Chris
    Chris

  9. AnonB Avatar
    AnonB

    Does this also cover fp1,fp2,fp3 and qualifying? And if so how long after those sessions will the data be available

  10. Admin Avatar
    Admin

    Hi AnonB,
    Qualifying is available from 2003 onwards. It’s usually available within 2-6 hours of the session ending. I don’t have time to process the FP data as it’s on a working day.
    Chris

  11. Malcoln Avatar

    Hi, thanks for the API, i’m gonna use it to build a website to study python+flask.. I’m just curious, where do you get the data from? Do you scrap f1.com?

    Thanks

  12. Peter Avatar
    Peter

    Hi Chris,

    Is there a way to get the time the qualifying session and the actual race is? Would be great to be able to retrieve those.

  13. Admin Avatar
    Admin

    Hi Peter,
    The race start time is in the race table.
    http://ergast.com/api/f1/current.json
    It is quite difficult to find the time of the other sessions at the time the race schedule is published. Potentially, it could be added later.
    Chris

  14. Bob Avatar
    Bob

    Hi Chris,

    Awesome website here! I’m trying to learn getting the whole proces automated from API till BI dashboard. I was wondering whether you know about any official data accessible on;
    – pitstop insights. Like the stop duration (e.g. 2.6 sec) and changed tires, nose, etc.
    – circuit data (turns, elevation, length, etc).

    Would be great to get any of this for the analyses part. Doesn’t have to be integrated on your side.

    Bob

  15. Admin Avatar
    Admin

    Hi Bob,
    It’s a long time since I had a look to see what was available. I recommend the FIA website – each race has a “Timing & Information” page e.g. https://www.fia.com/events/fia-formula-one-world-championship/season-2020/formula-1-70th-anniversary-grand-prix
    Chris

  16. Steve Avatar
    Steve

    Hi Chris,

    Fantastic API you have here! Does it include live timings and intervals during the race, or is this available on the F1 website only? I am looking for this data on the web but seems it is only provided by the official page.

    Thanks!
    Steve

  17. Admin Avatar
    Admin

    Hi Steve,
    Unfortunately we aren’t able to provide live data. It would be a reasonable thing for a sport to provide for its fans.
    Chris

  18. Bruno Freitas Avatar
    Bruno Freitas

    I’m using this URL to get all races listing https://ergast.com/api/f1/current.json on the current season, but how can I know which one of those are the last race that occurred? Do I have to compare its time with current Date()?

  19. Admin Avatar
    Admin

    Hi Bruno,
    The last race is always: https://ergast.com/api/f1/current/last.json
    And the next race is: https://ergast.com/api/f1/current/next.json
    Cheers,
    Chris

  20. Bruno Freitas Avatar
    Bruno Freitas

    But thats not my problem, When I ping only https://ergast.com/api/f1/current.json there is no way to know which of those are the last one, So I need to ping 2 API’s just to know which races have already occurred or not. A simple way to solve that, was just adding a key like “lastRound”: 6;

    I’m missing something? Thanks a lot for your effort, this service is Awesome!!!

  21. Admin Avatar
    Admin

    Hi Bruno,
    That’s true – but if the current/next logic was added to the schedule query it would be slower.
    Chris

  22. Aymar Tissedre Avatar
    Aymar Tissedre

    Hi,

    Is it possible to retrieve the time of free practices sessions and qualifications ?

    Thanks

  23. Admin Avatar
    Admin

    Hi Aymar,
    No – the API doesn’t include that data. It’s hard to find these times early in the season when they would be needed.
    Chris

  24. Aymar Tissedre Avatar
    Aymar Tissedre

    I see. I understand the problematic.

    Thank you for the hard work though !

  25. AG Avatar
    AG

    Hi, just wondering if the actual queries run by the endpoints are documented anywhere? I’m trying to work out in particular the logic for a query to return the final or latest season standings and the query to return all championship winners

  26. Admin Avatar
    Admin

    Hi AG,
    If you mean the SQL queries they’re in the runtime source code here: https://github.com/jcnewell/ergast-f1-api/tree/master/webroot/php/api
    If you mean the REST API then create your query with the web form and examine the URL it loads here: http://ergast.com/mrd/query/
    Cheers,
    Chris

  27. FCB Avatar
    FCB

    Hi,

    Is there a way to fetch a flat table from the API?
    like the standings table?
    to get just the foreign keys id’s and not the whole related tables data?

    Thanks!

  28. Admin Avatar
    Admin

    Hi FCB,
    Not from the API – but you can download the CSV files here: http://ergast.com/mrd/db/
    There’s one file per table.
    Chris

  29. Sergey Avatar
    Sergey

    Hello, I have a couple of questions.
    1. how do you get your data? parse the f1 website?
    2. will information on tire types and sectors Be available?
    3. If not, where can I find this information?

  30. Admin Avatar
    Admin

    Hi Sergey,
    The data is from various public sources. IIRC the sector times are available from https://www.fia.com but I’ve never found a reliable source of tyre data.
    Chris

  31. Ian Avatar
    Ian

    Hello,

    Firstly, thank you for the API, it’s fantastic.

    I noticed a possible issue with the Alpha Tauri constructor id. It seems that the constructor id changes from “alphatauri” to “alpha_tauri” in the API return for qualifying since round 12 of the current season.

    Is this something that can be fixed or should I adjust my system to account for the possibility?

    Thanks,

    Ian

  32. Admin Avatar
    Admin

    Hi Ian,
    Thanks for the warning. It was an error – now corrected.
    Chris

  33. Stefano Avatar
    Stefano

    Hi,
    I’m programming in javascript, how can I get the identification code to access the API ??
    Example:
    xhttp.setRequestHeader (“X-Auth-Token”, “identification code”);
    Thanks

  34. arek Avatar
    arek

    Hello,
    data in the API is available in few hours after the race, but what with the .csv files? how much time it take to make .csv file up to date?
    Thanks for great job
    Arek

  35. Admin Avatar
    Admin

    Hi Stefano,
    You don’t need any authentication code to access the API. Can you explain a little more about the issue you are experiencing?
    Chris

  36. Admin Avatar
    Admin

    Hi Arek,
    All the database dumps are available around the time the data becomes available unless there are technical issues.
    Chris

  37. Stefano Avatar
    Stefano

    Fixed thanks anyway

  38. Bob Avatar
    Bob

    Hi there!

    Is is possible to easily get the driver info of the 1st position of every lap (of a race)? Without using the limit of 1000. Which doesn’t even get all the lap results for some races (20 drivers x 71 laps for example).

    I want to be able to show a graph where it shows the drivers leading the race.

    Awesome API btw πŸ˜‰

    Bob

  39. Admin Avatar
    Admin

    Hi Bob,
    Unfortunately not. The method could do with the option of a position parameter, which I’ll consider.
    Chris

  40. Lukasz Avatar
    Lukasz

    Hi,

    could you please explain, what column “Wins” indicates here
    http://ergast.com/api/f1/driverstandings/1?limit=30&offset=60

    I’m trying to get drivers grouped by the number of they Grand Prix wins, to list from those who won most, using SQL (used DB image to load data to my playground MySQL), but got lost.

    Thx in advance for a hint.

    Best regards;
    Lukasz

  41. Admin Avatar
    Admin

    Hi Lukasz,
    > could you please explain, what column β€œWins” indicates
    It is the number of races won in the season indicated.

    > I’m trying to get drivers grouped by the number of they Grand Prix wins
    I think you would have to make a driver standings query for each season and sum the “wins” for each driver over all the seasons.
    Cheers,
    Chris

  42. SK Avatar
    SK

    Hi,

    Thanks a lot for this resource!

    I’ve been working on the dump of your database, I noticed that there is a number of cases where the grid value in results table is set to zero for ~40 results in last 20 years. see for example here http://ergast.com/api/f1/2020/3/results for magnussen
    That clearly contradicts official records —
    https://www.formula1.com/en/results.html/2020/races/1047/hungary/starting-grid.html

    Regards,
    S

  43. Admin Avatar
    Admin

    Hi SK,
    There’s a note on the documentation page for the results method that says a grid position value of 0 means the driver started from the pit lane. IIRC Kevin Magnussen went into the pits for technical reasons at the end of the formation lap.
    Chris

  44. DM Avatar
    DM

    Hi,

    Is it possible to have / find more circuit informations like fastest lap of the circuit, number of lap, circuit length ?

  45. Admin Avatar
    Admin

    Hi DM,
    It’s possible to find the fastest lap and number of laps for a specific race in the race results response. Remember that circuit configurations often change from year to year so circuit-based statistics would be difficult.
    Cheers,
    Chris

  46. David Avatar
    David

    Hi Chris,

    Firstly, thanks for this incredible project !

    I’m searching the data about the position of a constructor and points win by a constructor for a race of a season.

    I saw a Constructor Results in the db schema here http://ergast.com/mrd/db/ but couldn’t find the endpoint.

  47. Admin Avatar
    Admin

    Hi David,
    There has never been an endpoint for the Constructor results but I guess I could add one. Currently the race results are listed for each driver

    e.g. http://ergast.com/api/f1/2020/3/results

    so you have to loop thru the response and collate the constructor points.
    Cheers,
    Chris

  48. David Avatar
    David

    Hi Chris,

    Is it possible to inverse the order of the results of an api call to have from modern to old.

    Example:
    I want to list the last 10 seasons of a constructor.

    Currently, I have to increase the limit parameter of the api call to get all the seasons and trim the results to have only the last 10 results.

    So if I can inverse from last to first, the limit increase will no more be necessary resulting a better performance.

  49. Admin Avatar
    Admin

    Hi David,
    No, but the “total” attribute tells you the number of results, so you can make a second call with an offset which gives you the last ten.
    Cheers,
    Chris

  50. John Avatar

    Hi There,

    I am busy building a web app for a few mates for F1.

    I am going to be using this API to update my results. If I could map out my DB in the same way you have, It would make communication between the two so much easier.

    Is there any chance you can send me the schema for your DB (F1 only) so that I can save a lot of time.

    Thanks
    John

Leave a Reply

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