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 within 3 hrs.

19 Responses to “FAQ”

  1. Admin says:

    Add any further questions you would like answered here.

  2. Kieren says:

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

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

    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!

    Results capture is semi-automatic, using Wikipedia (since I use Wikipedia URLs as unique identifiers for all entities) with manual checking against FIA records before publication.

  5. Luke says:

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

    Hi Luke,

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

  7. Luke says:

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

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

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

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

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

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

    Hey,

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

    Cheers,

    James

  14. Admin says:

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

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

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

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

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

    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.

Add a Comment: