Ergast Developer API

The Ergast database Entity Relationship Diagram and the Database User Guide have been updated to include the new sprint results table and the additional session schedule information in the races table. Feedback welcome.

This year the race schedule will include information about all the race sessions e.g. FP 1-3, qualifying and sprint races. In general, dates will be provided for all sessions but session times may be missing until they have been confirmed.

Keeping the schedule up to date can be challenging, so if you see changes reported in the news do let me know if I’ve missed them.

Note that the current or future availability of sprint qualifying data is indicated by the presence of a Sprint element in the race schedule entry.

Sprint qualifying results will be properly supported during the 2022 season and data for the sprint races in 2021 has been added retrospectively. For details of the new API method and response format see the documentation page. Feedback between now and the beginning of the season would be very welcome.

Note that the sprint qualifying points were previously aggregated with the race points in the race results. They are now recorded separately – and last year’s race results have been amended. Apologies if this breaks existing code but I couldn’t think of a better way to introduce the change going forward.

I’ve added a provisional schedule for 2022 and some ‘zero point’ standings which will yield provisional lists of drivers and constructors using the following URLs:

• http://ergast.com/api/f1/2022/driverStandings
• http://ergast.com/api/f1/2022/constructorStandings

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)

Let me know if you spot any errors.

FYI I’ve had to introduce an automatic process for blocking users who violate the rate limits specified in the Terms & Conditions. This is because of a rogue app in circulation which is spamming the API.

Unfortunately, this might catch developers working on app development – when the real concern is apps published and distributed to multiple users.

If you find yourself blocked it should clear within 24 hours of your request rate dropping within the allowed rate. Apologies for any inconvenience.

Python requests has now been unblocked as the rogue Python app has been identified and an alternative approach has been found to protect the API server. Apologies for anyone adversely affected by the temporary block.

Due to a Python app breaking the Terms and Conditions by sending a deluge of requests I have blocked requests with the user agent strings:

“python-requests/2.26.0”
“python-requests/2.25.1”

Apologies if you’re affected. You can circumvent the block by setting a custom user agent string but please check first that your app is not calling the API in a continuous loop.

If you’ve published a Python app or wrapper recently would you please check that you are conforming to the rules stated in the Terms and Conditions – specifically the rules concerning calling the API in a loop. The site is currently experiencing very heavy traffic from a Python app where each instance is repeatedly making three requests every 8 seconds. If this continues I will have to block all traffic using Python which would be unfair on other users. If anyone spots an app which might be the source of this traffic please let me know via: admin@ergast.com so I can contact the author.

As an increasing number of users are working with the database dumps rather than with the API I’ve added a Database User Guide to the information on the Database Images page. Feedback would be very welcome.

Following a user request I’ve created a Entity Relationship Diagram describing the internal structure of the Ergast database. I’ve also added a file providing the MySQL table definitions in case people need them. These are both available from the Database Images page.

Using a similar approach to last year, ‘zero point’ standings have been added which will yield provisional lists of drivers and constructors:

http://ergast.com/api/f1/2021/driverStandings
http://ergast.com/api/f1/2021/constructorStandings

Unfortunately, there isn’t an easy way to associate drivers with constructors until after the first race due to the structure of the database.

Apologies to anyone who sent an email in late November / early December and didn’t get a reply. The site was moved to a new server and a chunk of email went missing. I’m a bit clueless about email servers :-/

Using a similar approach to last year, ‘zero point’ standings have been added which will yield provisional lists of drivers and constructors:

http://ergast.com/api/f1/2020/driverStandings

http://ergast.com/api/f1/2020/constructorStandings

Unfortunately, there isn’t an easy way to associate drivers with constructors until after the first race due to the structure of the database.

Following requests from several users, the CSV files published after each race now include the column headers on the first line of each file. These headers match the field names in the database tables.

In previous years, driver and constructor listings have not been available until after the results for the first race become available. This year, ‘zero point’ standings have been added which will yield provisional lists of drivers and constructors:

http://ergast.com/api/f1/2019/driverStandings

http://ergast.com/api/f1/2019/constructorStandings

Following a number of requests, the database image is now available in a PostgreSQL compatible data dump and as set of CSV files. These are updated after each race and following any corrections. See the Database Images page for details.

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!