API Documentation
The Ergast Developer API is an experimental web service which provides a historical record of motor racing data for non-commercial purposes. Please read the terms and conditions of use. Currently the API provides data for the Formula 1 series, from the 1980 season onwards.
The API will remain stable throughout the 2010 season during which it will track the emerging results.
If you have any comments or suggestions please post them on the Feedback page. If you find any bugs or errors in the data please report them on the Bug Reports page. Any enhancements to the API will be reported on the News page. Example applications are shown in the Application Gallery.
Overview
All API queries require a GET request using a URL of the form:
http://ergast.com/api/<series>/<season>/<round>/...
where:
<series> |
should be set to "f1" |
<season> |
is a 4 digit integer |
<round> |
is 1 or 2 digit integer |
For queries concerning a whole season, or final standings, the round element may be omitted. For example:
http://ergast.com/api/f1/2008/...
For queries concerning the whole series both the round and the season elements may be omitted. For example:
http://ergast.com/api/f1/...
To specify the current season the <season> field may be set to "current". To specify the previous or next race within a season the <round> field may be set to "last" or "next" respectively. For example:
http://ergast.com/api/f1/2005/last/...
http://ergast.com/api/f1/current/next/...
For more information about these shortcuts see the FAQ.
The type of information returned by a query is determined by the remainder of the URL. The following options are available:
| Season List | Race Schedule | Race Results |
| Qualifying Results | Standings | Driver Information |
| Constructor Information | Circuit Information | Finishing Status |
You can generate URLs to query the database using the Query Database page.
Response formats
The API currently supports XML and JSON response formats. XML is returned by default or when ".xml" is appended to URLs. JSON is selected by appending ".json" to URLs.
XML responses conform to the Ergast Motor Racing XML Schema.
Response paging
As a large number of results may be available the number returned can be controlled using a limit query parameter. If not specified the default limit is 30.
An offset into the result set can also be specified using an offset query parameter. If not specified the default offset is zero. For example, the following URL returns the third page of driver information containing ten entries per page:
http://ergast.com/api/f1/drivers?limit=10&offset=20
The total number of available results is indicated by a total attribute in the root element of the response.