ErgastApiClient - C# library for querying the Ergast Developer API (Formula 1 data)

ErgastApiClient - C# library for querying the Ergast Developer API (Formula 1 data)

The Ergast Developer API ( is an awesome (experimental) web service which provides a historical record of Formula 1 data for non-commercial purposes. The API contains data all the back to the beginning in 1950.

Some time ago I wanted to query some of this data and make some charts of lap times, gap to leader etc. from the latest F1 races, but I couldn't find any .NET library for it. I could have just made some simply calls to the specific endpoints I needed, but I like to make libraries, soo...

I still haven't gotten around to the chart part, but at least I've finished the library.

The library can be installed from NuGet - search for ErgastApiClient or install it through the Package Manger Console:

PM> Install-Package ErgastApiClient

If you are not a programmer but want to query the data anyway you can use the manual interface.

Using the library

The library is pretty simple to use. Create (and reuse) an ErgastClient and then create one of the many request types:

  • RaceResultsRequest
  • LapTimesRequest
  • PitStopsRequest
  • CircuitInfoRequest
  • DriverInfoRequest
  • DriverStandingsRequest
  • ...

You then use the client to execute the request and it will return a matching response type. The client takes care of caching for you, so you don't query the Ergast web service unnecessarily.

Below is a complete example of doing a RaceResultsRequest.

// Relevant imports
using ErgastApi.Client;
using ErgastApi.Ids;
using ErgastApi.Requests;

// The client should be stored and reused during the lifetime of your application
var client = new ErgastClient();

// All request properties are optional (except 'Season' if 'Round' is set)
var request = new RaceResultsRequest
    Season = "2017",     // or Seasons.Current for current season
    Round = "11",        // or Rounds.Last or Rounds.Next for last or next round
    DriverId = "vettel", // or Drivers.SebastianVettel

    Limit = 30      // Limit the number of results returned
    Offset = 0      // Result offset (used for paging)

// RaceResultsRequest returns a RaceResultsResponse
// Other requests returns other response types
RaceResultsResponse response = await client.GetResponseAsync(request);

// We know it's only a single race, round 11
var race = response.Races.First();

race.Round;                // 11
race.RaceName;             // Hungarian Grand Prix
race.Circuit.CircuitName;  // Hungaroring

// There is only one driver in the results - Vettel
// Otherwise the results would be ordered by finishing position
var vettel = race.Results[0];

vettel.Driver.Code;           // VET
vettel.FastestLap.LapNumber;  // 69
vettel.Position;              // 1 (finishing position)

The RaceResultsResponse contains a list of races matching the query. In this example there is only the one race (Round 11, Hungary, 2017). Each race contains info about the race, the circuit, time of the event etc. and of course the race results.

Each result (in this case there is only Vettel) contains info about the driver, finishing position, starting position (Grid), fastest lap etc.

The above example is the equivalent of this manual query. You can also see the actual JSON data by adding .json to the URL of the manual request.

Source code

The source code is available on GitHub which also has some more examples of how you can use the library/Ergast API.

If you encounter any bugs or have a feature request, please create an issue on GitHub. Pull Requests are also very welcome.