Ergast Developer API

By: tonyh

Building on the release of the open source runtime, which provides the code required to run a version of the API on your own server using an Ergast database image, the runtime code repository has been updated to include a configuration script that can be used to launch the runtime and a database server using Docker containers linked by docker-compose.

The configuration builds two containers locally:

• a MySQL database container seeded with the most recent Ergast database image;
• a web server container running Apache and PHP 5 that serves the Ergast API using the same API paths as ergast.com.

In its current configuration, the database server can also be used to serve database requests to other linked containers. For example, the docker-compose.yaml includes a commented out example of how to connect a containing running RStudio, and how to connect to the database from an R script. To make the database API available outside the docker container, an additional --ports setting is required to expose the server port (3306).

The original runtime code is still available for use, either inside or outside Docker as part of your own API server, in the ./webroot directory.

https://github.com/jcnewell/ergast-f1-api

About Docker: Docker is a virtualisation platform that allows applications to run in lightweight virtual containers on remote hosts or locally.

If you use Docker on your own desktop, you can serve the ergast API locally on your own computer, and access it via localhost using the normal API paths, such as http://localhost:8000/api/f1/2017.json.

After requests from several users I’ve added support for HTTPS across the API. Let me know if you encounter any problems using it.

Following several requests, the API runtime has been released on GitHub, under the Apache 2.0 open-source license.

https://github.com/jcnewell/ergast-f1-api

This allows people to deploy their own servers using an Ergast database image.

Hopefully, contributors may also improve the code and develop additional features!

A kind contributor has provided additional lap time data from 1996 up to the end of the 2010 season, where the data previously started. This provides a total of 20 years worth of lap time data for you to analyse! The missing lap times for the Brazilian Grand Prix in 2014 have also been added. Thanks MB.

Ergast is pleased to announce support for the new FIA Formula E Championship on an experimental basis throughout the first season of the new series.

URLs are identical to those required for Formula One except that the series identifier changes to "fe" e.g.

http://ergast.com/api/fe/current/last/results

Currently there is no data for fastest laps, lap times or pit stops.

Feedback and suggestions would be very welcome.

Following a number of requests, an updated Ergast MySQL database image is now available after each race, rather than at the end of the season. Check the date on the download page if you want the most recent version.

This is a post to confirm that the API will continue throughout 2014 and will track the results as they become available. The only significant change this year is the addition of the permanent driver numbers. Note that the “current” shortcut refers to 2013 until after the first race of the new season. Standings and driver or constructor listings for 2014 are only available after the first race.

The database image issued at the end of the 2013 season has been revised as the source of some character encoding problems has been identified. If you have used the earlier version you may need to re-import data using the new image. The character encoding should now always be set to “utf8”.

Drivers participating in the 2014 season onwards now have a permanent driver number. For these drivers there is a new PermanentNumber field in the Driver element. However, the value may sometimes differ from the value of the existing position attribute in the Result and QualifyingResult elements. This will occur in earlier seasons or where the reigning champion has chosen to use “1” rather than his permanent driver number, as Sebastian Vettel has done this year.

To accommodate this change the schema has been updated to: mrd-1.4.xsd

The 2013 end of season MySQL database dump has been updated to take account of some recent corrections. There is also now an ANSI compatible version, which may be helpful for converting to other SQL formats such as SQLite. Both of these are available here: http://ergast.com/mrd/db

Now the season has ended, we’ve taken the opportunity to move the site onto a VPS which we’ve been preparing throughout the autumn. As far as we can tell, the transition has happened smoothly but if you spot any problems please let us know. The move has been motivated by a growth in traffic which occasionally caused problems in the previous shared hosting service. The new VPS should provide more headroom and maintain responsiveness, which is important for your sites and apps. However, to achieve the best results, it’s important to cache queries at your server and in your clients.

A new database image is available covering all seasons up to and including 2013: http://ergast.com/mrd/db

I’m usually very reluctant to make any mid-season changes to the API but recent events have required a change to keep the API running. There was an increasing number of very large queries (some attempting to download all results since 1950!) which have put a heavy load on the server, in terms of memory and processor time. Since the API currently uses shared hosting this has caused problems for other websites and I was asked to take action to avoid the API being suspended.

The on-going change is a new maximum value of 1000 for the ‘limit’ query parameter. This will let you download a full season of results or a full list of all drivers, constructors, circuits etc. However, please use the smallest value that your applications requires, preferably only requesting the information you need to present in the current view. Please also implement caching as much as possible, either (or both) on your server and in your applications. This will improve the performance of your applications and for other API users. If you require large amounts of historical data please consider downloading the database image rather than polling the API.

Meanwhile, the Ergast site will be moving to a Virtual Private Server to improve performance and reduce the impact of heavy traffic on other websites.

Pressure of work and the disappointing absence of any reliable source of tyre data means that there are few changes to the API for the 2013 season.

The only new feature is the introduction of the official three letter codes for each driver. Wherever the Driver element appears (i.e. in the Driver, Race and Standings tables) there is a new “code” attribute for all drivers from the 2005 season onwards.

The only significant change to the API is that the Result element now has both a “position” attribute (which is always an integer) and a “positionText” attribute (which is an integer when the driver is classified or a letter to signal their finishing status).

Looking forward to the first race of the season, and checking-in the first set of results to the API database!

This post is to confirm that the Ergast API will continue to provide F1 results throughout the 2013 season and beyond. There have been a number of requests for enhancements:

– three letter codes for drivers
– driver photos
– drivers and teams listed before the first race
– explicit position / unclassified status
– tyre data (dependent on finding a data source)

If you have any other suggestions please let me know although I can’t promise to implement all of them.

Looking forward to seeing your new apps for the 2013 season!

A new database image is available covering all seasons up to and including 2012: http://ergast.com/mrd/db

Ergast is pleased to announce the publication of a complete image of the Ergast database. This is made available under the Attribution-NonCommercial-ShareAlike 3.0 Unported Licence and will be updated at the end of each season. The image allows you to create an exact copy of the MySQL database for your own purposes. Let us know what you do with it.

Ergast is pleased to announce that Lap Time and Pit Stop data will be available throughout the 2012 season on an experimental basis – this means the data may not be available as quickly as race results and will not be subject to the same degree of manual checking due to the volume of information. See the new Lap Times and Pit Stops documentation pages for more details. The API also provides a complete set of this data for the 2011 season. Feedback on the new API methods and data validity would be very much appreciated.

Following a number of requests I’ve added JSONP as an alternative response format. This allows client-side applications to access the API without the restrictions of the same origin policy imposed by browsers.

JSONP is obtained by appending ".json" to URLs and a query parameter named "callback" which must specify a valid Javascript function name. For example:

http://ergast.com/api/f1/drivers.json?callback=myParser

Let me know if you find any problems or build something interesting with it!

One other change this year which has not been documented is the removal of the “dob” attribute from the Driver element in the results and driver standings XML responses. The attribute is unnecessary because there is a DateOfBirth sub-element.

It’s probably worth pointing out that, in addition to appearing in race results, fastest lap rankings can now be used as a parameter in all queries except Standings queries. For example, you can list all the drivers who achieved the fastest lap in a season using the following URL:

http://ergast.com/api/f1/2010/fastest/1/drivers

Or all races where a particular driver achieved the fastest lap:

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

Fastest lap timings have now been added from the 2004 season onwards.

The changes for the 2011 season described earlier have been implemented and were introduced this evening. If you spot any problems please let me know. Barring any problems the API will now remain unchanged for the remainder of the year. Happy coding!

This post is to confirm that the Ergast API will continue to provide F1 results throughout the 2011 season. The only technical change will be an updated schema that provides fastest lap times in race results. In addition, whitespace has been removed from JSON responses. These changes will be introduced in the API on 15th February. Initially, fastest lap times will only be available for the 2010 season but will then be introduced progressively for earlier years over the next month or so.

Hope to see some new apps ready for the 2011 season!

Some proposed changes to the API for 2011:

1) The race results response will be extended to include the fastest laps times for all drivers. The provisional documentation is here: http://ergast.com/mrd/results

2) The indentation and whitespace will be removed from JSON responses for efficiency reasons.

I’m about to start implementing these changes so any comments or suggestions you have would be very welcome.

This post is to confirm that the Ergast API will continue to provide F1 results throughout the 2010 season. The only technical change will be a move to an updated XML schema that allows multiple drivers per car. This will allow the API to cover the 1950s accurately, where car sharing was common. The change will come into effect on 1st January.

Added an Application Gallery to showcase applications using the Ergast Developer API. If you would like to add your application or mashup to the gallery please contact us with details.

Added a Query Page with forms which generate URLs and query the database.

Added optional JSON response format. Needs further testing.

First release of the API provides data for the Formula 1 series from the 2000 season onwards. The eventual goal is to add data back to the 1950s.

The first supported response format is XML but JSON is under development.

Not much thought has gone into error conditions and responses so I guess that may need more attention.