ErgastApiClient 1.2.2

A client for querying the Ergast Developer API (http://ergast.com/mrd/)

There is a newer prerelease version of this package available.
See the version list below for details.
Install-Package ErgastApiClient -Version 1.2.2
dotnet add package ErgastApiClient --version 1.2.2
<PackageReference Include="ErgastApiClient" Version="1.2.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add ErgastApiClient --version 1.2.2
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Usage

Start by creating an ErgastClient. Then create on of the request types and set parameters to narrow down your query.
Execute the request throughe the client with the GetResponseAsync(IErgastRequest) method.

Below is an example of how to get the race results of the 11th race of the 2017 season.

// 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);

The following request types are available:

  • Race & Results
    • CircuitInfoRequest
    • ConstructorInfoRequest
    • DriverInfoRequest
    • FinishingStatusRequest
    • QualifyingResultsRequest
    • RaceListRequest
    • RaceResultsRequest
    • SeasonListRequest
  • Standings
    • ConstructorStandingsRequest
    • DriverStandingsRequest
  • Lap Times & Pit Stops
    • LapTimesRequest
    • PitStopsRequest

Here are some other examples:

// List of seasons where Alonso won the WDC and Ferrari got second in the WCC
new SeasonListRequest
{
    DriverId = Drivers.FernandoAlonso,
    DriverStanding = 1,

    ConstructorId = Constructors.Ferrari,
    ConstructorStanding = 2
}

// List of races where Raikkonen retired because
// of engine problems while racing for Ferrari
new RaceListRequest
{
    DriverId = Drivers.KimiRaikkonen,
    ConstructorId = Constructors.Ferrari,
    FinishingStatus = FinishingStatusId.Engine
}

// Qualifying results from last round
new QualifyingResultsRequest
{
    Season = Seasons.Current,
    Round = Rounds.Last
}

// Driver standings after race 3 in 2017
new DriverStandingsRequest
{ 
    Season = "2017", 
    Round = "3"
}

// List of circuits where Hamilton got pole, won the race
// and set fastest lap time while racing for McLaren
new CircuitInfoRequest
{
    DriverId = Drivers.LewisHamilton,
    ConstructorId = Constructors.McLaren,
    QualifyingPosition = 1,
    FinishingPosition = 1,
    FastestLapRank = 1
}

// Drivers who have won the race at Baku
new DriverInfoRequest
{
    CircuitId = Circuits.Baku,
    FinishingPosition = 1
}

Driver, constructor and circuit IDs

Most current IDs are stored as constants in the Drivers, Constructors and Circuits static classes.

Drivers.SebastianVettel // "vettel"
Constructors.Ferrari    // "ferrari"
Circuits.Monza          // "monza"

If the ID you are looking for is not listed there, then you will have to query the API with either
a DriverInfoRequest, ConstructorInfoRequest or CircuitInfoRequest.

Here is how you could find the ID of Fernando Alonso:

// Get drivers in current season (leave out season to get a list of all drivers ever (requires paging))
var request = new DriverInfoRequest { Limit = 1000 }
var response = await client.GetResponseAsync(request);

response.Drivers.Single(x => x.FullName == "Fernando Alonso").DriverId;

Paging

Some responses will have a lot of results. Every request type has two properties used for paging - Limit and Offset.

The Limit property allows you to limit the number of returned results.
The maximum value is 1000 but please use the smallest value that you can. If not set it defaults to 30.

The Offset property specifies an offset into the result set (i.e. start from this position).
If not set it defaults to zero.

The response object returned from ErgastClient.GetResponseAsync() contains the following information to help you with paging:

  • Limit and Offset (the values used for the response)
  • TotalResults
  • Page
  • TotalPages
  • HasMorePages

Caching

ErgastClient caches the response for all requests to minimize the load on the API server. Requests are cached by the resulting URL.

The default cache lifetime is one hour. You can change this by setting client.Cache.CacheEntryLifetime to a different TimeSpan value.

You can clear the cache by calling client.Cache.Clear().

TODOs

  • Add helper methods for getting next/previous page
  • Add more XML documentation for better intellisense
  • Add more unit tests

Usage

Start by creating an ErgastClient. Then create on of the request types and set parameters to narrow down your query.
Execute the request throughe the client with the GetResponseAsync(IErgastRequest) method.

Below is an example of how to get the race results of the 11th race of the 2017 season.

// 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);

The following request types are available:

  • Race & Results
    • CircuitInfoRequest
    • ConstructorInfoRequest
    • DriverInfoRequest
    • FinishingStatusRequest
    • QualifyingResultsRequest
    • RaceListRequest
    • RaceResultsRequest
    • SeasonListRequest
  • Standings
    • ConstructorStandingsRequest
    • DriverStandingsRequest
  • Lap Times & Pit Stops
    • LapTimesRequest
    • PitStopsRequest

Here are some other examples:

// List of seasons where Alonso won the WDC and Ferrari got second in the WCC
new SeasonListRequest
{
    DriverId = Drivers.FernandoAlonso,
    DriverStanding = 1,

    ConstructorId = Constructors.Ferrari,
    ConstructorStanding = 2
}

// List of races where Raikkonen retired because
// of engine problems while racing for Ferrari
new RaceListRequest
{
    DriverId = Drivers.KimiRaikkonen,
    ConstructorId = Constructors.Ferrari,
    FinishingStatus = FinishingStatusId.Engine
}

// Qualifying results from last round
new QualifyingResultsRequest
{
    Season = Seasons.Current,
    Round = Rounds.Last
}

// Driver standings after race 3 in 2017
new DriverStandingsRequest
{ 
    Season = "2017", 
    Round = "3"
}

// List of circuits where Hamilton got pole, won the race
// and set fastest lap time while racing for McLaren
new CircuitInfoRequest
{
    DriverId = Drivers.LewisHamilton,
    ConstructorId = Constructors.McLaren,
    QualifyingPosition = 1,
    FinishingPosition = 1,
    FastestLapRank = 1
}

// Drivers who have won the race at Baku
new DriverInfoRequest
{
    CircuitId = Circuits.Baku,
    FinishingPosition = 1
}

Driver, constructor and circuit IDs

Most current IDs are stored as constants in the Drivers, Constructors and Circuits static classes.

Drivers.SebastianVettel // "vettel"
Constructors.Ferrari    // "ferrari"
Circuits.Monza          // "monza"

If the ID you are looking for is not listed there, then you will have to query the API with either
a DriverInfoRequest, ConstructorInfoRequest or CircuitInfoRequest.

Here is how you could find the ID of Fernando Alonso:

// Get drivers in current season (leave out season to get a list of all drivers ever (requires paging))
var request = new DriverInfoRequest { Limit = 1000 }
var response = await client.GetResponseAsync(request);

response.Drivers.Single(x => x.FullName == "Fernando Alonso").DriverId;

Paging

Some responses will have a lot of results. Every request type has two properties used for paging - Limit and Offset.

The Limit property allows you to limit the number of returned results.
The maximum value is 1000 but please use the smallest value that you can. If not set it defaults to 30.

The Offset property specifies an offset into the result set (i.e. start from this position).
If not set it defaults to zero.

The response object returned from ErgastClient.GetResponseAsync() contains the following information to help you with paging:

  • Limit and Offset (the values used for the response)
  • TotalResults
  • Page
  • TotalPages
  • HasMorePages

Caching

ErgastClient caches the response for all requests to minimize the load on the API server. Requests are cached by the resulting URL.

The default cache lifetime is one hour. You can change this by setting client.Cache.CacheEntryLifetime to a different TimeSpan value.

You can clear the cache by calling client.Cache.Clear().

TODOs

  • Add helper methods for getting next/previous page
  • Add more XML documentation for better intellisense
  • Add more unit tests

Release Notes

- Fixed issues with half points (they were being attempted parsed as `int`)
- Added constructors info to driver standings
- Fixed error with Q1 sometimes being an empty string causing a parsing error

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version History

Version Downloads Last updated
2.0.0-rc 143 7/19/2019
1.2.2 581 9/11/2017
1.1.0 334 8/20/2017