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

    Add any further questions you would like answered here.

  2. Kieren Avatar
    Kieren

    The API looks fantastic. I was just wondering, for the coming season, how soon after a round do you expect the data be available via the API?

    Admin: Kieren – I’ve added a comment above.

  3. Vito A Avatar

    Very cool! I was wondering why the delay for the race results? Are you grabbing the data automatically from the formula1.com website, or are you entering the race data manually into your database?

  4. Admin Avatar
    Admin

    Hi Vito. The delay has typically been around 2 hrs this season. In the future it will depend when the race starts relative to my local time and whether I am dedicated enough to be awake!

  5. Luke Avatar
    Luke

    Great work, just a little question regarding client-side access:
    Are you considering JSONP as a response format?

    Thanks, keep up the good work!

  6. Admin Avatar
    Admin

    Hi Luke,

    I’d consider it, if there’s a demand. Would you use it?

  7. Luke Avatar
    Luke

    If it was available I would! I wouldn’t add it for me alone, but if others think it a good idea (and you think it would be beneficial) I’d definitely use it over JSON or XML for prototyping.

  8. James Avatar

    Would it be acceptable to store any of this information temporarily in a database to reduce hits on the API? A little like Google maps allows with their Geoencoding API?

  9. Admin Avatar
    Admin

    Hi James,

    No problem. You can do what you like with the data as long as any service you provide from it is within the Terms and Conditions.

    Chris

  10. Matt Avatar
    Matt

    I would definitely use JSONP. With JSONP I could build a client-only application for custom statistics, without having to use a proxy to circumvent the cross-domain-policy.

    Currently I’m thinking about a “what would the standings be with the old point system” page (or any custom point system).

  11. Admin Avatar
    Admin

    Ok, I’ve added JSONP support to the Race Schedule call for people to try. If you include a query parameter called “callback” in the URL you’ll get JSONP rather than JSON.

    e.g. http://ergast.com/api/f1/2011.json?callback=parseSchedule

    Feedback would be appreciated. If people are happy with this approach I’ll add it throughout the API.

    Notes:

    1. Content-type changes to “application/javascript”

    2. Any non-alphanumeric characters are stripped from the callback parameter value.

  12. Admin Avatar
    Admin

    I’ve now added JSONP support to all the API calls.

    The callback parameter value must be a valid Javascript function name otherwise you get a “400 Bad Request” error.

    Let me know if you build anything interesting with it.

  13. James Avatar

    Hey,

    I was wondering if there’s an ordering parameter that can be added to the api query?

    Cheers,

    James

  14. Admin Avatar
    Admin

    Hi James,

    No – most queries have an obvious ordering for the data so I’ve used that as the default. Let me know if you have a particular requirement in mind.

    Chris

  15. Rob Avatar
    Rob

    This site is great. Would it be possible to add engine manufacturer information as well as constructor? Teams have often switched engine supplier and this is an important factor in their performance. Similarly engine rules era, for example V6 Turbo, V8 and V10. When the engine rules have changed there has frequently been a shake-up which we are now experiencing with the move to the current regulations. This would make a fantastic data source even more useful and complete. Thanks!

  16. Admin Avatar
    Admin

    Hi Rob,

    Good idea. I’ll consider it for next year as I don’t like to make changes to the API mid-season. Is the engine-constructor relationship ever likely to change mid-season?

  17. Rob Avatar
    Rob

    Cool, thanks for your reply and positivity.

    I don’t think a constructor has changed engine supplier mid-season certainly in the last 20 years or so from memory. It may have happened in the early days.

  18. Paulo Pires Avatar
    Paulo Pires

    Hello.

    Great work with this API!

    I have one question, which timezone are you using in the start time of the GP, for example?

    Ty.

  19. Admin Avatar
    Admin

    Hi Paulo,

    Thanks for the positive comments. The API uses UTC for the start times, as denoted by the “Z” suffix. If you spot any errors let me know – I don’t always get things right or spot re-scheduling.

  20. John Avatar
    John

    Hi,

    Was wondering if there is any data around the web or here that denotes when Safety Cars have been deployed during races ?

  21. Admin Avatar
    Admin

    Hi John,

    Not that I’m aware of, unfortunately.

  22. Rumen Avatar
    Rumen

    Hi John,

    You may query lap times for that. If laptime > laptime*10%(previous lap) => safety car.

  23. Dom Avatar

    Any scope for doing this in real time?

    Cheers,
    Dom

  24. Admin Avatar
    Admin

    Hi Dom,

    Do you mean real-time lap times? Unfortunately, those aren’t openly published AFAIK.

  25. Rogerio Brito Avatar

    Hello,

    First of all, congratulations on great job! Well done!

    I’d like to list all races where a Driver had the fastest race lap.
    Can you please help me build a SQL Query that does that?

    Thank you

  26. Admin Avatar
    Admin

    Hi Rogerio,

    For a specific season the query would be:

    http://ergast.com/api/f1/2013/fastest/1/results

    For a specific driver the query would be:

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

    You can also combine the season and driver parameters.

    Hope that helps,

    Chris

  27. Rogerio Brito Avatar

    Hello Chris,

    I’m using a local database image… can you please help me with a MySQL query?
    Thanks!!!

  28. Admin Avatar
    Admin

    Hi Rogerio,

    Ah ok. In the results table the “rank” field is the fastest laps ranking for each race, so filter on rank=’1′ e.g.

    SELECT
    SQL_CALC_FOUND_ROWS
    ra.year, ra.round, ra.name, ra.date, ra.time, ra.url,
    ci.circuitRef, ci.name, ci.location, ci.country, ci.url, ci.lat, ci.lng, ci.alt,
    re.grid, re.positionText, re.positionOrder, re.number, re.points, re.laps, re.time, re.milliseconds, re.rank, re.fastestLap, re.fastestLapTime, re.fastestLapSpeed,
    dr.driverRef, dr.number, dr.code, dr.forename, dr.surname, dr.dob, dr.nationality, dr.url,
    st.statusId, st.status,
    co.constructorRef, co.name, co.nationality, co.url

    FROM
    races ra, circuits ci, results re, drivers dr, constructors co, status st

    WHERE
    ra.circuitId=ci.circuitId AND ra.raceId=re.raceId AND re.driverId=dr.driverId AND re.constructorId=co.constructorId AND re.statusId=st.statusId AND dr.driverRef='alonso' AND re.rank='1'

    ORDER BY
    ra.year, ra.round

  29. Rogerio Brito Avatar

    Hi Chris,

    Excellent!
    Thank you very much!!!

  30. Manuel Avatar
    Manuel

    Hi,

    I would like to ask you guys if does anybody use the API with Ruby on Rails or know how to use it.
    I´m trying to do it and I am really stack with it. Im calling the next:
    http://ergast.com/api/f1/2014/driverStandings.json
    And try to parse it in order to show in my a list, such as:

    Drivers Championship Standings
    1 Lewis Hamilton Mercedes 384

    I have tried many differents way but I cant, I did with angular but unfortunately I need to do just with Rails.

    I would realy appreciatte if you can give me a hand.

    Thanks

  31. Admin Avatar
    Admin

    Hi Manuel,
    Sorry – I can’t help you with Ruby. Perhaps someone at Rails Forum could help? There’s also a Ruby wrapper for the Ergast API.
    Chris

  32. Marco Avatar
    Marco

    Hi!

    This site is fantastic really. The best database for formula one I’ve seen.

    Can you please tell me how is it possible to Import these data with Excel? It’s really annoying to do so manually.

    Thanks again for this site!

    Marco

  33. Admin Avatar
    Admin

    Hi Marco,
    Thanks for the positive comments. There’s some advice on direct import to Excel here:
    http://excelramblings.blogspot.co.uk/2012/04/json-data-for-all-f1-races-straight.html

  34. Pheaxx Avatar
    Pheaxx

    Hi,

    first of all, thanks for your dedication to suply us with data :).

    I have one question, is there any reason why the “contructors” table does not have a “driverid”?

    if posible could you add it to the table?

    keep up the good work!

    Pheaxx

  35. Admin Avatar
    Admin

    Hi Pheaxx,
    The reason the constructors table doesn’t have a driverId field is to decouple drivers from teams. This is because drivers frequently move between teams – sometimes even mid-season! You can identify the drivers associated with a constructor in a particular year by doing an SQL join between the driver, constructor, races and results tables. That’s what happens if you call this method:
    http://ergast.com/api/f1/2015/constructors/ferrari/drivers

  36. Fox Avatar
    Fox

    Hi,
    is it possible to download JSON file?
    Thanks

  37. A Avatar
    A

    It seems that for example http://ergast.com/api/f1/2016/1 contains only a start time of the actual race. Is there a possibility to get starting times for all practice and qualifying sessions also?

  38. Admin Avatar
    Admin

    Hi A,
    Do you know of a reliable source of the additional start times? Preferably in UTC.

  39. Admin Avatar
    Admin

    Hi Fox,
    Do you mean a JSON file representing the entire database?

  40. Whiskey Avatar
    Whiskey

    Hello, is there any way to retrieve an amount of constructor championships for a driver?
    By the way, this is an excellent database! Really glad I’ve found it 🙂

  41. Admin Avatar
    Admin

    Hi Whiskey,

    Unfortunately you can’t do this in one query. One method would be to get all the seasons for a driver e.g.

    http://ergast.com/api/f1/drivers/alonso/seasons

    Then find the constructors for each season e.g.

    http://ergast.com/api/f1/2001/drivers/alonso/constructors

    Then check whether they won the championship e.g.

    http://ergast.com/api/f1/2001/constructors/minardi/constructorStandings/1

  42. avalon Avatar
    avalon

    Very useful API. Saves me the time of scraping this stuff myself. Thanks!

  43. Admin Avatar
    Admin

    Thanks for the positive comments avalon.
    Let me know if you build something interesting.
    Chris

  44. James Murrell Avatar
    James Murrell

    as always this is best every api… when will the database image be updated for download

  45. Admin Avatar
    Admin

    Done (sorry – got distracted yesterday)

  46. James Murrell Avatar
    James Murrell

    No worries, wished i could help…… and Thank you:

  47. silk Avatar
    silk

    Hi, thank you for offering this wonderful resource and making it accessible so easily.

    My questions are related to the pitstops.
    (1) There appear to be two formats for pitstop duration: E.g. 27.831 and 18:09.312.
    Is this an error (the times seem to differ quite a lot) and if not, how should I interpret the second format (xx:xx.xxx). These results are derived from: http://ergast.com/api/f1/current/last/pitstops

    My second question is: the pitstop times appear to be the period from pitlane entry to pitlane exit. Are they date on the actual ‘stopping’ time also available?

    Thanks,

    Richard

  48. Admin Avatar
    Admin

    Hi Richard,
    The duration format is: [[[M]M:]S]S.sss (i.e. minutes and the following hyphen are omitted for durations of less than one minute). The long duration in your example was the result of a red flag period.

    Unfortunately, the actual stopping time is not made available AFAIK.

  49. James Murrell Avatar
    James Murrell

    Hello, when will the database image be updated for download

  50. Admin Avatar
    Admin

    Hi James,
    Done. I should automate this.
    Chris