Ergast API Interface¶

Introduction¶

This module can be used to interface with the Ergast F1 API (https://ergast.com/mrd/). All Ergast endpoints are supported.

The Ergast object provides access to all API Endpoints of the Ergast API.

The terms of use of Ergast apply (https://ergast.com/mrd/terms/). Especially take care not to exceed the specified rate limits. FastF1 will handle caching and it will try to enforce rate limits where possible. Make sure to know what limits apply. For more information on how FastF1 handles caching and rate limiting see Requests and Caching.

Result Types¶

Data can be returned in two different formats:

Raw Response

ErgastRawResponse

Provides the raw JSON-like response data from Ergast.

This format is a JSON-like representation of the original JSON data (using json.load).

Flattened into Pandas DataFrames

`ErgastSimpleResponse`	Provides simple Ergast result data in the form of a Pandas `DataFrame`.
`ErgastMultiResponse`	Provides complex Ergast result data in the form of multiple Pandas `DataFrames`.

The complexity of the data that is returned by the API endpoint determines the exact result type. The return type is documented for each endpoint.

An ErgastSimpleResponse wraps a Pandas DataFrame directly.

An ErgastMultiResponse consists of a descriptive DataFrame (description) and a list of DataFrames that contain the main content of the response (content).

General Options¶

The following arguments are available as default values on Ergast or individually for each endpoint method:

result_type (‘raw’ or ‘pandas’): Select between RAW responses or
Pandas DataFrame responses.

auto_cast (bool): Select whether all values are automatically
cast from their default string representation to the most appropriate data type.

limit (int): Set the limit for the maximum number of results that
are returned in one request. The server default (30 results) applies if this value is not set. The maximum allowed value is 1000 results.

Common Surprises¶

This is a list of things that may be surprising or unexpected for first-time users.

API results are always returned in ascending order. As a result, for example, if you query the race schedule without specifying a season, you will receive the schedule for the oldest seasons first, starting in 1950.

Only some combinations of filter parameters are possible and those vary for each API endpoint. FastF1 does not impose restrictions on these combinations as the relationships are fairly complex. Instead, an ErgastInvalidRequestError will be returned in such a case. The exception will contain the error response of the server.

Examples¶

First, import Ergast and create and interface with all default arguments.

>>> from fastf1.ergast import Ergast
>>> ergast = Ergast()

Simple DataFrame Responses¶

Get information about all circuits that hosted a Grand Prix in 2022. This is an endpoint that returns an ErgastSimpleResponse, meaning one single DataFrame.

>>> response_frame = ergast.get_circuits(season=2022)
>>> response_frame
        circuitId  ...       country
0     albert_park  ...     Australia
1        americas  ...           USA
2         bahrain  ...       Bahrain
...
19     villeneuve  ...        Canada
20     yas_marina  ...           UAE
21      zandvoort  ...   Netherlands

[22 rows x 7 columns]

Raw Responses¶

To get the raw data instead of the DataFrame result, specify the return type as ‘raw’:

>>> ergast.get_circuits(season=2022, result_type='raw')  
[{'circuitId': 'albert_park',
  'url': 'http://en.wikipedia.org/wiki/Melbourne_Grand_Prix_Circuit',
  'circuitName': 'Albert Park Grand Prix Circuit',
  'Location': {'lat': -37.8497,
               'long': 144.968,
               'locality': 'Melbourne',
               'country': 'Australia'}},
...]

Note that FastF1’s “raw” response is not actually the complete JSON response that the API provides. Instead, only the actual data part of the response is returned while metadata (version, query parameters, response length, …) are not included.

Renamed Keys and Type Casting¶

In the response DataFrame, some keys are renamed from the raw result so that all column names are unique when flattening more complex responses. Compare the column names from the result data frame with the raw response above and note that ‘url’ has changed to ‘circuitUrl’ (Responses can include other URLs as well).

>>> response_frame.columns
Index(['circuitId', 'circuitUrl', 'circuitName', 'lat', 'long', 'locality',
       'country'],
      dtype='object')

Also note, that by default all values will automatically be cast to the most suitable data type. Ergast itself does provide all values as string, though. Automatic type casting can be very useful because most of the time it will make it easier to work with the data. But it is possible to disable automatic type casting by setting auto_cast=False. For example, by default auto casting is enabled and ‘lat’ and ‘long’ will be cast to float,

>>> ergast.get_circuits(season=2022, result_type='raw')[0]['Location']
{'lat': -37.8497, 'long': 144.968, 'locality': 'Melbourne', 'country': 'Australia'}

but with auto_cast=False both values remain str.

>>> ergast.get_circuits(season=2022, result_type='raw', auto_cast=False)[0]['Location']
{'lat': '-37.8497', 'long': '144.968', 'locality': 'Melbourne', 'country': 'Australia'}

The documentation for each API endpoint includes an “API Mapping” that shows the structure of the raw response, the updated key names for flattening and the data types for automatic type casting. Additionally, there is a “DataFrame Description” that shows which column names will be present in the result frame. This way it easy to see which keys are renamed. Additionally, both the “API Mapping” and the “DataFrame Description” will show the data type to which a value is cast when auto_cast=True.

Note

-1 is used to indicate missing values for int-type values (int does not support a proper NaN value)

MultiResponse DataFrames¶

There are API endpoints that return complex data structures as a response. When ‘pandas’ is selected as result type, these endpoints return a ErgastMultiResponse. One such endpoint is the constructor standings endpoint.

>>> standings = ergast.get_constructor_standings()  

Called without any ‘season’ specifier, it returns standings for multiple seasons. An overview over the returned data is available as a .description of the response:

>>> standings.description  
   season  round
0    1958     11
1    1959      9
2    1960     10

Note that the API always returns results in an ascending order. Therefore, when no season is specified, the constructor standings are returned for the oldest available seasons.

Due to the maximum number of returned results being limited, only data for three seasons is returned, as can be seen.

The actual standings information is available in separate DataFrames for each season. These can be accessed as .content of the response. The first element in .content is associated with the first row of the .description and so on.

>>> standings.content[0]  
   position positionText  ...  constructorName  constructorNationality
0         1            1  ...          Vanwall                 British
1         2            2  ...          Ferrari                 Italian
...
7         8            8  ...        Connaught                 British
8         9            9  ...             OSCA                 Italian

[9 rows x 8 columns]

Pagination¶

All Ergast response objects inherit from ErgastResponseMixin. This object provides support for pagination on all response objects. Ergast uses pagination to serve results for specific requests on multiple ‘pages’ when the response exceeds the limit for the maximum number of results.

For example, when limiting the sesason list to three results, Ergast responds with:

>>> seasons = ergast.get_seasons(limit=3)
>>> seasons
   season                                          seasonUrl
0    1950  http://en.wikipedia.org/wiki/1950_Formula_One_...
1    1951  http://en.wikipedia.org/wiki/1951_Formula_One_...
2    1952  http://en.wikipedia.org/wiki/1952_Formula_One_...

It is possible to check whether a response contains all results and to obtain the total number of results:

>>> seasons.is_complete
False
>>> seasons.total_results 
74

Now, the builtin pagination can be used to obtain the next result page. The same limit as before is used.

>>> seasons.get_next_result_page()
   season                                          seasonUrl
0    1953  http://en.wikipedia.org/wiki/1953_Formula_One_...
1    1954  http://en.wikipedia.org/wiki/1954_Formula_One_...
2    1955  http://en.wikipedia.org/wiki/1955_Formula_One_...

It is also possible to manually specify an offset into the dataset:

>>> ergast.get_seasons(limit=3, offset=6)
   season                                          seasonUrl
0    1956  http://en.wikipedia.org/wiki/1956_Formula_One_...
1    1957  http://en.wikipedia.org/wiki/1957_Formula_One_...
2    1958  http://en.wikipedia.org/wiki/1958_Formula_One_...

API Reference¶

Main Interface¶

class fastf1.ergast.Ergast(result_type='pandas', auto_cast=True, limit=None)[source]¶

The main object that acts as an interface to the Ergast API.

For each API endpoint, there is a separate method implemented to request data.

Parameters:

result_type (Literal['raw', 'pandas']) –
Determines the default type of the returned result object
- ’raw’: ErgastRawResponse
- ’pandas’: ErgastSimpleResponse or ErgastMultiResponse depending on endpoint
auto_cast (bool) – Determines whether result values are cast from there default string representation to a better matching type
limit (Optional[int]) – The maximum number of results returned by the API. Defaults to 30 if not set. Maximum: 1000. See also “Response Paging” on https://ergast.com/mrd/.

get_seasons(circuit=None, constructor=None, driver=None, grid_position=None, results_position=None, fastest_rank=None, status=None, result_type=None, auto_cast=None, limit=None, offset=None)[source]¶

Get a list of seasons.

See: https://ergast.com/mrd/methods/seasons/

API Mapping

Structure of the raw response, renamed key names for flattening and dtypes for automatic type casting:

[
    {
        season: season <int>,
        url: seasonUrl <str>
    }
]

DataFrame Description

DataFrame column names and dtypes for automatic typecasting:

season       <int>
seasonUrl    <str>

Parameters:

circuit (Optional[str]) – select a circuit by its circuit id (default: all)
constructor (Optional[str]) – select a constructor by its constructor id (default: all)
driver (Optional[str]) – select a driver by its driver id (default: all)
grid_position (Optional[int]) – select a grid position by its number (default: all)
results_position (Optional[int]) – select a finishing result by its position (default: all)
fastest_rank (Optional[int]) – select fastest by rank number (default: all)
status (Optional[str]) – select by finishing status (default: all)
result_type (Optional[Literal['pandas', 'raw']]) – Overwrites the default result type
auto_cast (Optional[bool]) – Overwrites the default value for auto_cast
limit (Optional[int]) – Overwrites the default value for limit
offset (Optional[int]) – An offset into the result set for response paging. Defaults to 0 if not set. See also “Response Paging”, https://ergast.com/mrd/.

Return type:

Union[ErgastSimpleResponse, ErgastRawResponse]

Returns:

ErgastSimpleResponse or ErgastRawResponse, depending on the result_type parameter

get_race_schedule(season, round=None, circuit=None, constructor=None, driver=None, grid_position=None, results_position=None, fastest_rank=None, status=None, result_type=None, auto_cast=None, limit=None, offset=None)[source]¶

Get a list of races.

See: https://ergast.com/mrd/methods/schedule/

API Mapping

Structure of the raw response, renamed key names for flattening and dtypes for automatic type casting:

[
    {
        season: season <int>,
        round: round <int>,
        url: raceUrl <str>,
        raceName: raceName <str>,
        date: raceDate <Optional>,
        time: raceTime <Optional>,
        Circuit: {
            circuitId: circuitId <str>,
            url: circuitUrl <str>,
            circuitName: circuitName <str>,
            Location: {
                lat: lat <float>,
                long: long <float>,
                locality: locality <str>,
                country: country <str>
            }
        },
        FirstPractice: {
            date: fp1Date <Optional>,
            time: fp1Time <Optional>
        },
        SecondPractice: {
            date: fp2Date <Optional>,
            time: fp2Time <Optional>
        },
        ThirdPractice: {
            date: fp3Date <Optional>,
            time: fp3Time <Optional>
        },
        Qualifying: {
            date: qualifyingDate <Optional>,
            time: qualifyingTime <Optional>
        },
        Sprint: {
            date: sprintDate <Optional>,
            time: sprintTime <Optional>
        }
    }
]

DataFrame Description

DataFrame column names and dtypes for automatic typecasting:

season                 <int>
round                  <int>
raceUrl                <str>
raceName               <str>
raceDate          <Optional>
raceTime          <Optional>
circuitId              <str>
circuitUrl             <str>
circuitName            <str>
lat                  <float>
long                 <float>
locality               <str>
country                <str>
fp1Date           <Optional>
fp1Time           <Optional>
fp2Date           <Optional>
fp2Time           <Optional>
fp3Date           <Optional>
fp3Time           <Optional>
qualifyingDate    <Optional>
qualifyingTime    <Optional>
sprintDate        <Optional>
sprintTime        <Optional>

Parameters:

season (Union[Literal['current'], int]) – select a season by its year (default: all, oldest first)
round (Union[Literal['last'], int, None]) – select a round by its number (default: all)
circuit (Optional[str]) – select a circuit by its circuit id (default: all)
constructor (Optional[str]) – select a constructor by its constructor id (default: all)
driver (Optional[str]) – select a driver by its driver id (default: all)
grid_position (Optional[int]) – select a grid position by its number (default: all)
results_position (Optional[int]) – select a finishing result by its position (default: all)
fastest_rank (Optional[int]) – select fastest by rank number (default: all)
status (Optional[str]) – select by finishing status (default: all)
result_type (Optional[Literal['pandas', 'raw']]) – Overwrites the default result type
auto_cast (Optional[bool]) – Overwrites the default value for auto_cast
limit (Optional[int]) – Overwrites the default value for limit
offset (Optional[int]) – An offset into the result set for response paging. Defaults to 0 if not set. See also “Response Paging”, https://ergast.com/mrd/.

Return type:

Union[ErgastSimpleResponse, ErgastRawResponse]

Returns:

ErgastSimpleResponse or ErgastRawResponse, depending on the result_type parameter

get_driver_info(season=None, round=None, circuit=None, constructor=None, driver=None, grid_position=None, results_position=None, fastest_rank=None, status=None, result_type=None, auto_cast=None, limit=None, offset=None)[source]¶

Get a list of drivers.

See: https://ergast.com/mrd/methods/drivers/

API Mapping

Structure of the raw response, renamed key names for flattening and dtypes for automatic type casting:

[
    {
        driverId: driverId <str>,
        permanentNumber: driverNumber <int>,
        code: driverCode <str>,
        url: driverUrl <str>,
        givenName: givenName <str>,
        familyName: familyName <str>,
        dateOfBirth: dateOfBirth <Optional>,
        nationality: driverNationality <str>
    }
]

DataFrame Description

DataFrame column names and dtypes for automatic typecasting:

driverId                  <str>
driverNumber              <int>
driverCode                <str>
driverUrl                 <str>
givenName                 <str>
familyName                <str>
dateOfBirth          <Optional>
driverNationality         <str>

Parameters:

season (Union[Literal['current'], int, None]) – select a season by its year (default: all, oldest first)
round (Union[Literal['last'], int, None]) – select a round by its number (default: all)
circuit (Optional[str]) – select a circuit by its circuit id (default: all)
constructor (Optional[str]) – select a constructor by its constructor id (default: all)
driver (Optional[str]) – select a driver by its driver id (default: all)
grid_position (Optional[int]) – select a grid position by its number (default: all)
results_position (Optional[int]) – select a finishing result by its position (default: all)
fastest_rank (Optional[int]) – select fastest by rank number (default: all)
status (Optional[str]) – select by finishing status (default: all)
result_type (Optional[Literal['pandas', 'raw']]) – Overwrites the default result type
auto_cast (Optional[bool]) – Overwrites the default value for auto_cast
limit (Optional[int]) – Overwrites the default value for limit
offset (Optional[int]) – An offset into the result set for response paging. Defaults to 0 if not set. See also “Response Paging”, https://ergast.com/mrd/.

Return type:

Union[ErgastSimpleResponse, ErgastRawResponse]

Returns:

ErgastSimpleResponse or ErgastRawResponse, depending on the result_type parameter

get_constructor_info(season=None, round=None, circuit=None, constructor=None, driver=None, grid_position=None, results_position=None, fastest_rank=None, status=None, result_type=None, auto_cast=None, limit=None, offset=None)[source]¶

Get a list of constructors.

See: https://ergast.com/mrd/methods/constructors/

API Mapping

Structure of the raw response, renamed key names for flattening and dtypes for automatic type casting:

[
    {
        constructorId: constructorId <str>,
        url: constructorUrl <str>,
        name: constructorName <str>,
        nationality: constructorNationality <str>
    }
]

DataFrame Description

DataFrame column names and dtypes for automatic typecasting:

constructorId             <str>
constructorUrl            <str>
constructorName           <str>
constructorNationality    <str>

Parameters:

season (Union[Literal['current'], int, None]) – select a season by its year (default: all, oldest first)
round (Union[Literal['last'], int, None]) – select a round by its number (default: all)
circuit (Optional[str]) – select a circuit by its circuit id (default: all)
constructor (Optional[str]) – select a constructor by its constructor id (default: all)
driver (Optional[str]) – select a driver by its driver id (default: all)
grid_position (Optional[int]) – select a grid position by its number (default: all)
results_position (Optional[int]) – select a finishing result by its position (default: all)
fastest_rank (Optional[int]) – select fastest by rank number (default: all)
status (Optional[str]) – select by finishing status (default: all)
result_type (Optional[Literal['pandas', 'raw']]) – Overwrites the default result type
auto_cast (Optional[bool]) – Overwrites the default value for auto_cast
limit (Optional[int]) – Overwrites the default value for limit
offset (Optional[int]) – An offset into the result set for response paging. Defaults to 0 if not set. See also “Response Paging”, https://ergast.com/mrd/.

Return type:

Union[ErgastSimpleResponse, ErgastRawResponse]

Returns:

ErgastSimpleResponse or ErgastRawResponse, depending on the result_type parameter

get_circuits(season=None, round=None, constructor=None, driver=None, grid_position=None, results_position=None, fastest_rank=None, status=None, result_type=None, auto_cast=None, limit=None, offset=None)[source]¶

Get a list of circuits.

See: https://ergast.com/mrd/methods/circuits/

API Mapping

Structure of the raw response, renamed key names for flattening and dtypes for automatic type casting:

[
    {
        circuitId: circuitId <str>,
        url: circuitUrl <str>,
        circuitName: circuitName <str>,
        Location: {
            lat: lat <float>,
            long: long <float>,
            locality: locality <str>,
            country: country <str>
        }
    }
]

DataFrame Description

DataFrame column names and dtypes for automatic typecasting:

circuitId        <str>
circuitUrl       <str>
circuitName      <str>
lat            <float>
long           <float>
locality         <str>
country          <str>

Parameters:

season (Union[Literal['current'], int, None]) – select a season by its year (default: all, oldest first)
round (Union[Literal['last'], int, None]) – select a round by its number (default: all)
constructor (Optional[str]) – select a constructor by its constructor id (default: all)
driver (Optional[str]) – select a driver by its driver id (default: all)
grid_position (Optional[int]) – select a grid position by its number (default: all)
results_position (Optional[int]) – select a finishing result by its position (default: all)
fastest_rank (Optional[int]) – select fastest by rank number (default: all)
status (Optional[str]) – select by finishing status (default: all)
result_type (Optional[Literal['pandas', 'raw']]) – Overwrites the default result type
auto_cast (Optional[bool]) – Overwrites the default value for auto_cast
limit (Optional[int]) – Overwrites the default value for limit
offset (Optional[int]) – An offset into the result set for response paging. Defaults to 0 if not set. See also “Response Paging”, https://ergast.com/mrd/.

Return type:

Union[ErgastSimpleResponse, ErgastRawResponse]

Returns:

ErgastSimpleResponse or ErgastRawResponse, depending on the result_type parameter

get_finishing_status(season=None, round=None, circuit=None, constructor=None, driver=None, grid_position=None, results_position=None, fastest_rank=None, status=None, result_type=None, auto_cast=None, limit=None, offset=None)[source]¶

Get a list of finishing status codes.

See: https://ergast.com/mrd/methods/status/

API Mapping

Structure of the raw response, renamed key names for flattening and dtypes for automatic type casting:

[
    {
        statusId: statusId <int>,
        count: count <int>,
        status: status <str>
    }
]

DataFrame Description

DataFrame column names and dtypes for automatic typecasting:

statusId    <int>
count       <int>
status      <str>

Parameters:

season (Union[Literal['current'], int, None]) – select a season by its year (default: all, oldest first)
round (Union[Literal['last'], int, None]) – select a round by its number (default: all)
circuit (Optional[str]) – select a circuit by its circuit id (default: all)
constructor (Optional[str]) – select a constructor by its constructor id (default: all)
driver (Optional[str]) – select a driver by its driver id (default: all)
grid_position (Optional[int]) – select a grid position by its number (default: all)
results_position (Optional[int]) – select a finishing result by its position (default: all)
fastest_rank (Optional[int]) – select fastest by rank number (default: all)
status (Optional[str]) – select by finishing status (default: all)
result_type (Optional[Literal['pandas', 'raw']]) – Overwrites the default result type
auto_cast (Optional[bool]) – Overwrites the default value for auto_cast
limit (Optional[int]) – Overwrites the default value for limit
offset (Optional[int]) – An offset into the result set for response paging. Defaults to 0 if not set. See also “Response Paging”, https://ergast.com/mrd/.

Return type:

Union[ErgastSimpleResponse, ErgastRawResponse]

Returns:

ErgastSimpleResponse or ErgastRawResponse, depending on the result_type parameter

get_race_results(season=None, round=None, circuit=None, constructor=None, driver=None, grid_position=None, results_position=None, fastest_rank=None, status=None, result_type=None, auto_cast=None, limit=None, offset=None)[source]¶

Get race results for one or multiple races.

See: https://ergast.com/mrd/methods/results/

API Mapping

Structure of the raw response, renamed key names for flattening and dtypes for automatic type casting:

[
    {
        season: season <int>,
        round: round <int>,
        url: raceUrl <str>,
        raceName: raceName <str>,
        date: raceDate <Optional>,
        time: raceTime <Optional>,
        Circuit: {
            circuitId: circuitId <str>,
            url: circuitUrl <str>,
            circuitName: circuitName <str>,
            Location: {
                lat: lat <float>,
                long: long <float>,
                locality: locality <str>,
                country: country <str>
            }
        },
        Results: [
            {
                number: number <int>,
                position: position <int>,
                positionText: positionText <str>,
                points: points <float>,
                grid: grid <int>,
                laps: laps <int>,
                status: status <str>,
                Driver: {
                    driverId: driverId <str>,
                    permanentNumber: driverNumber <int>,
                    code: driverCode <str>,
                    url: driverUrl <str>,
                    givenName: givenName <str>,
                    familyName: familyName <str>,
                    dateOfBirth: dateOfBirth <Optional>,
                    nationality: driverNationality <str>
                },
                Constructor: {
                    constructorId: constructorId <str>,
                    url: constructorUrl <str>,
                    name: constructorName <str>,
                    nationality: constructorNationality <str>
                },
                Time: {
                    millis: totalRaceTimeMillis <int>,
                    time: totalRaceTime <Optional>
                },
                FastestLap: {
                    rank: fastestLapRank <int>,
                    lap: fastestLapNumber <int>,
                    Time: {
                        millis: fastestLapTimeMillis <int>,
                        time: fastestLapTime <Optional>
                    },
                    AverageSpeed: {
                        units: fastestLapAvgSpeedUnits <str>,
                        speed: fastestLapAvgSpeed <float>
                    }
                },
                AverageSpeed: {
                    units: fastestLapAvgSpeedUnits <str>,
                    speed: fastestLapAvgSpeed <float>
                }
            }
        ]
    }
]

DataFrame Description

DataFrame column names and dtypes for automatic typecasting:

ErgastMultiResponse.description

season              <int>
round               <int>
raceUrl             <str>
raceName            <str>
raceDate       <Optional>
raceTime       <Optional>
circuitId           <str>
circuitUrl          <str>
circuitName         <str>
lat               <float>
long              <float>
locality            <str>
country             <str>

ErgastMultiResponse.content (contains data from subkey RaceResults)

number                          <int>
position                        <int>
positionText                    <str>
points                        <float>
grid                            <int>
laps                            <int>
status                          <str>
driverId                        <str>
driverNumber                    <int>
driverCode                      <str>
driverUrl                       <str>
givenName                       <str>
familyName                      <str>
dateOfBirth                <Optional>
driverNationality               <str>
constructorId                   <str>
constructorUrl                  <str>
constructorName                 <str>
constructorNationality          <str>
totalRaceTimeMillis             <int>
totalRaceTime              <Optional>
fastestLapRank                  <int>
fastestLapNumber                <int>
fastestLapTimeMillis            <int>
fastestLapTime             <Optional>
fastestLapAvgSpeedUnits         <str>
fastestLapAvgSpeed            <float>

Parameters:

season (Union[Literal['current'], int, None]) – select a season by its year (default: all, oldest first)
round (Union[Literal['last'], int, None]) – select a round by its number (default: all)
circuit (Optional[str]) – select a circuit by its circuit id (default: all)
constructor (Optional[str]) – select a constructor by its constructor id (default: all)
driver (Optional[str]) – select a driver by its driver id (default: all)
grid_position (Optional[int]) – select a grid position by its number (default: all)
results_position (Optional[int]) – select a finishing result by its position (default: all)
fastest_rank (Optional[int]) – select fastest by rank number (default: all)
status (Optional[str]) – select by finishing status (default: all)
result_type (Optional[Literal['pandas', 'raw']]) – Overwrites the default result type
auto_cast (Optional[bool]) – Overwrites the default value for auto_cast
limit (Optional[int]) – Overwrites the default value for limit
offset (Optional[int]) – An offset into the result set for response paging. Defaults to 0 if not set. See also “Response Paging”, https://ergast.com/mrd/.

Return type:

Union[ErgastMultiResponse, ErgastRawResponse]

Returns:

ErgastMultiResponse or ErgastRawResponse, depending on the result_type parameter

get_qualifying_results(season=None, round=None, circuit=None, constructor=None, driver=None, grid_position=None, results_position=None, fastest_rank=None, status=None, result_type=None, auto_cast=None, limit=None, offset=None)[source]¶

Get qualifying results for one or multiple qualifying sessions.

See: https://ergast.com/mrd/methods/qualifying/

API Mapping

Structure of the raw response, renamed key names for flattening and dtypes for automatic type casting:

[
    {
        season: season <int>,
        round: round <int>,
        url: raceUrl <str>,
        raceName: raceName <str>,
        date: raceDate <Optional>,
        time: raceTime <Optional>,
        Circuit: {
            circuitId: circuitId <str>,
            url: circuitUrl <str>,
            circuitName: circuitName <str>,
            Location: {
                lat: lat <float>,
                long: long <float>,
                locality: locality <str>,
                country: country <str>
            }
        },
        QualifyingResults: [
            {
                number: number <int>,
                position: position <int>,
                Q1: Q1 <Optional>,
                Q2: Q2 <Optional>,
                Q3: Q3 <Optional>,
                Driver: {
                    driverId: driverId <str>,
                    permanentNumber: driverNumber <int>,
                    code: driverCode <str>,
                    url: driverUrl <str>,
                    givenName: givenName <str>,
                    familyName: familyName <str>,
                    dateOfBirth: dateOfBirth <Optional>,
                    nationality: driverNationality <str>
                },
                Constructor: {
                    constructorId: constructorId <str>,
                    url: constructorUrl <str>,
                    name: constructorName <str>,
                    nationality: constructorNationality <str>
                }
            }
        ]
    }
]

DataFrame Description

DataFrame column names and dtypes for automatic typecasting:

ErgastMultiResponse.description

season              <int>
round               <int>
raceUrl             <str>
raceName            <str>
raceDate       <Optional>
raceTime       <Optional>
circuitId           <str>
circuitUrl          <str>
circuitName         <str>
lat               <float>
long              <float>
locality            <str>
country             <str>

ErgastMultiResponse.content (contains data from subkey QualifyingResults)

number                         <int>
position                       <int>
Q1                        <Optional>
Q2                        <Optional>
Q3                        <Optional>
driverId                       <str>
driverNumber                   <int>
driverCode                     <str>
driverUrl                      <str>
givenName                      <str>
familyName                     <str>
dateOfBirth               <Optional>
driverNationality              <str>
constructorId                  <str>
constructorUrl                 <str>
constructorName                <str>
constructorNationality         <str>

Parameters:

season (Union[Literal['current'], int, None]) – select a season by its year (default: all, oldest first)
round (Union[Literal['last'], int, None]) – select a round by its number (default: all)
circuit (Optional[str]) – select a circuit by its circuit id (default: all)
constructor (Optional[str]) – select a constructor by its constructor id (default: all)
driver (Optional[str]) – select a driver by its driver id (default: all)
grid_position (Optional[int]) – select a grid position by its number (default: all)
results_position (Optional[int]) – select a finishing result by its position (default: all)
fastest_rank (Optional[int]) – select fastest by rank number (default: all)
status (Optional[str]) – select by finishing status (default: all)
result_type (Optional[Literal['pandas', 'raw']]) – Overwrites the default result type
auto_cast (Optional[bool]) – Overwrites the default value for auto_cast
limit (Optional[int]) – Overwrites the default value for limit
offset (Optional[int]) – An offset into the result set for response paging. Defaults to 0 if not set. See also “Response Paging”, https://ergast.com/mrd/.

Return type:

Union[ErgastMultiResponse, ErgastRawResponse]

Returns:

ErgastMultiResponse or ErgastRawResponse, depending on the result_type parameter

get_sprint_results(season=None, round=None, circuit=None, constructor=None, driver=None, grid_position=None, results_position=None, status=None, result_type=None, auto_cast=None, limit=None, offset=None)[source]¶

Get sprint results for one or multiple sprints.

See: https://ergast.com/mrd/methods/sprint/

API Mapping

Structure of the raw response, renamed key names for flattening and dtypes for automatic type casting:

[
    {
        season: season <int>,
        round: round <int>,
        url: raceUrl <str>,
        raceName: raceName <str>,
        date: raceDate <Optional>,
        time: raceTime <Optional>,
        Circuit: {
            circuitId: circuitId <str>,
            url: circuitUrl <str>,
            circuitName: circuitName <str>,
            Location: {
                lat: lat <float>,
                long: long <float>,
                locality: locality <str>,
                country: country <str>
            }
        },
        SprintResults: [
            {
                number: number <int>,
                position: position <int>,
                positionText: positionText <str>,
                points: points <float>,
                grid: grid <int>,
                laps: laps <int>,
                status: status <str>,
                Driver: {
                    driverId: driverId <str>,
                    permanentNumber: driverNumber <int>,
                    code: driverCode <str>,
                    url: driverUrl <str>,
                    givenName: givenName <str>,
                    familyName: familyName <str>,
                    dateOfBirth: dateOfBirth <Optional>,
                    nationality: driverNationality <str>
                },
                Constructor: {
                    constructorId: constructorId <str>,
                    url: constructorUrl <str>,
                    name: constructorName <str>,
                    nationality: constructorNationality <str>
                },
                Time: {
                    millis: totalRaceTimeMillis <int>,
                    time: totalRaceTime <Optional>
                },
                FastestLap: {
                    rank: fastestLapRank <int>,
                    lap: fastestLapNumber <int>,
                    Time: {
                        millis: fastestLapTimeMillis <int>,
                        time: fastestLapTime <Optional>
                    },
                    AverageSpeed: {
                        units: fastestLapAvgSpeedUnits <str>,
                        speed: fastestLapAvgSpeed <float>
                    }
                },
                AverageSpeed: {
                    units: fastestLapAvgSpeedUnits <str>,
                    speed: fastestLapAvgSpeed <float>
                }
            }
        ]
    }
]

DataFrame Description

DataFrame column names and dtypes for automatic typecasting:

ErgastMultiResponse.description

season              <int>
round               <int>
raceUrl             <str>
raceName            <str>
raceDate       <Optional>
raceTime       <Optional>
circuitId           <str>
circuitUrl          <str>
circuitName         <str>
lat               <float>
long              <float>
locality            <str>
country             <str>

ErgastMultiResponse.content (contains data from subkey SprintResults)

number                          <int>
position                        <int>
positionText                    <str>
points                        <float>
grid                            <int>
laps                            <int>
status                          <str>
driverId                        <str>
driverNumber                    <int>
driverCode                      <str>
driverUrl                       <str>
givenName                       <str>
familyName                      <str>
dateOfBirth                <Optional>
driverNationality               <str>
constructorId                   <str>
constructorUrl                  <str>
constructorName                 <str>
constructorNationality          <str>
totalRaceTimeMillis             <int>
totalRaceTime              <Optional>
fastestLapRank                  <int>
fastestLapNumber                <int>
fastestLapTimeMillis            <int>
fastestLapTime             <Optional>
fastestLapAvgSpeedUnits         <str>
fastestLapAvgSpeed            <float>

Parameters:

season (Union[Literal['current'], int, None]) – select a season by its year (default: all, oldest first)
round (Union[Literal['last'], int, None]) – select a round by its number (default: all)
circuit (Optional[str]) – select a circuit by its circuit id (default: all)
constructor (Optional[str]) – select a constructor by its constructor id (default: all)
driver (Optional[str]) – select a driver by its driver id (default: all)
grid_position (Optional[int]) – select a grid position by its number (default: all)
results_position (Optional[int]) – select a finishing result by its position (default: all)
status (Optional[str]) – select by finishing status (default: all)
result_type (Optional[Literal['pandas', 'raw']]) – Overwrites the default result type
auto_cast (Optional[bool]) – Overwrites the default value for auto_cast
limit (Optional[int]) – Overwrites the default value for limit
offset (Optional[int]) – An offset into the result set for response paging. Defaults to 0 if not set. See also “Response Paging”, https://ergast.com/mrd/.

Return type:

Union[ErgastMultiResponse, ErgastRawResponse]

Returns:

ErgastMultiResponse or ErgastRawResponse, depending on the result_type parameter

get_driver_standings(season=None, round=None, driver=None, standings_position=None, result_type=None, auto_cast=None, limit=None, offset=None)[source]¶

Get driver standings at specific points of a season.

See: https://ergast.com/mrd/methods/standings/

API Mapping

Structure of the raw response, renamed key names for flattening and dtypes for automatic type casting:

[
    {
        season: season <int>,
        round: round <int>,
        DriverStandings: [
            {
                position: position <int>,
                positionText: positionText <str>,
                points: points <float>,
                wins: wins <int>,
                Driver: {
                    driverId: driverId <str>,
                    permanentNumber: driverNumber <int>,
                    code: driverCode <str>,
                    url: driverUrl <str>,
                    givenName: givenName <str>,
                    familyName: familyName <str>,
                    dateOfBirth: dateOfBirth <Optional>,
                    nationality: driverNationality <str>
                },
                Constructors: [
                    {
                        constructorId: constructorIds <str>,
                        url: constructorUrls <str>,
                        name: constructorNames <str>,
                        nationality: constructorNationalities <str>
                    }
                ]
            }
        ]
    }
]

DataFrame Description

DataFrame column names and dtypes for automatic typecasting:

ErgastMultiResponse.description

season    <int>
round     <int>

ErgastMultiResponse.content (contains data from subkey DriverStandings)

position                         <int>
positionText                     <str>
points                         <float>
wins                             <int>
driverId                         <str>
driverNumber                     <int>
driverCode                       <str>
driverUrl                        <str>
givenName                        <str>
familyName                       <str>
dateOfBirth                 <Optional>
driverNationality                <str>
constructorIds                 [<str>]
constructorUrls                [<str>]
constructorNames               [<str>]
constructorNationalities       [<str>]

Parameters:

season (Union[Literal['current'], int, None]) – select a season by its year (default: all, oldest first)
round (Union[Literal['last'], int, None]) – select a round by its number (default: all)
driver (Optional[str]) – select a driver by its driver id (default: all)
standings_position (Optional[int]) – select a result by position in the standings (default: all)
result_type (Optional[Literal['pandas', 'raw']]) – Overwrites the default result type
auto_cast (Optional[bool]) – Overwrites the default value for auto_cast
limit (Optional[int]) – Overwrites the default value for limit
offset (Optional[int]) – An offset into the result set for response paging. Defaults to 0 if not set. See also “Response Paging”, https://ergast.com/mrd/.

Return type:

Union[ErgastMultiResponse, ErgastRawResponse]

Returns:

ErgastMultiResponse or ErgastRawResponse, depending on the result_type parameter

get_constructor_standings(season=None, round=None, constructor=None, standings_position=None, result_type=None, auto_cast=None, limit=None, offset=None)[source]¶

Get constructor standings at specific points of a season.

See: https://ergast.com/mrd/methods/standings/

API Mapping

Structure of the raw response, renamed key names for flattening and dtypes for automatic type casting:

[
    {
        season: season <int>,
        round: round <int>,
        ConstructorStandings: [
            {
                position: position <int>,
                positionText: positionText <str>,
                points: points <float>,
                wins: wins <int>,
                Constructor: {
                    constructorId: constructorId <str>,
                    url: constructorUrl <str>,
                    name: constructorName <str>,
                    nationality: constructorNationality <str>
                }
            }
        ]
    }
]

DataFrame Description

DataFrame column names and dtypes for automatic typecasting:

ErgastMultiResponse.description

season    <int>
round     <int>

ErgastMultiResponse.content (contains data from subkey ConstructorStandings)

position                    <int>
positionText                <str>
points                    <float>
wins                        <int>
constructorId               <str>
constructorUrl              <str>
constructorName             <str>
constructorNationality      <str>

Parameters:

season (Union[Literal['current'], int, None]) – select a season by its year (default: all, oldest first)
round (Union[Literal['last'], int, None]) – select a round by its number (default: all)
constructor (Optional[str]) – select a constructor by its constructor id (default: all)
standings_position (Optional[int]) – select a result by position in the standings (default: all)
result_type (Optional[Literal['pandas', 'raw']]) – Overwrites the default result type
auto_cast (Optional[bool]) – Overwrites the default value for auto_cast
limit (Optional[int]) – Overwrites the default value for limit
offset (Optional[int]) – An offset into the result set for response paging. Defaults to 0 if not set. See also “Response Paging”, https://ergast.com/mrd/.

Return type:

Union[ErgastMultiResponse, ErgastRawResponse]

Returns:

ErgastMultiResponse or ErgastRawResponse, depending on the result_type parameter

get_lap_times(season, round, lap_number=None, driver=None, result_type=None, auto_cast=None, limit=None, offset=None)[source]¶

Get sprint results for one or multiple sprints.

See: https://ergast.com/mrd/methods/laps/

API Mapping

Structure of the raw response, renamed key names for flattening and dtypes for automatic type casting:

[
    {
        season: season <int>,
        round: round <int>,
        url: raceUrl <str>,
        raceName: raceName <str>,
        date: raceDate <Optional>,
        time: raceTime <Optional>,
        Circuit: {
            circuitId: circuitId <str>,
            url: circuitUrl <str>,
            circuitName: circuitName <str>,
            Location: {
                lat: lat <float>,
                long: long <float>,
                locality: locality <str>,
                country: country <str>
            }
        },
        Laps: [
            {
                number: number <int>,
                Timings: [
                    {
                        driverId: driverId <str>,
                        position: position <int>,
                        time: time <Optional>
                    }
                ]
            }
        ]
    }
]

DataFrame Description

DataFrame column names and dtypes for automatic typecasting:

ErgastMultiResponse.description

season              <int>
round               <int>
raceUrl             <str>
raceName            <str>
raceDate       <Optional>
raceTime       <Optional>
circuitId           <str>
circuitUrl          <str>
circuitName         <str>
lat               <float>
long              <float>
locality            <str>
country             <str>

ErgastMultiResponse.content (contains data from subkey Laps)

number           <int>
driverId         <str>
position         <int>
time        <Optional>

Parameters:

season (Union[Literal['current'], int]) – select a season by its year (default: all, oldest first)
round (Union[Literal['last'], int]) – select a round by its number (default: all)
lap_number (Optional[int]) – select lap times by a specific lap number (default: all)
driver (Optional[str]) – select a driver by its driver id (default: all)
result_type (Optional[Literal['pandas', 'raw']]) – Overwrites the default result type
auto_cast (Optional[bool]) – Overwrites the default value for auto_cast
limit (Optional[int]) – Overwrites the default value for limit
offset (Optional[int]) – An offset into the result set for response paging. Defaults to 0 if not set. See also “Response Paging”, https://ergast.com/mrd/.

Return type:

Union[ErgastMultiResponse, ErgastRawResponse]

Returns:

ErgastMultiResponse or ErgastRawResponse, depending on the result_type parameter

get_pit_stops(season, round, stop_number=None, lap_number=None, driver=None, result_type=None, auto_cast=None, limit=None, offset=None)[source]¶

Get pit stop information for one or multiple sessions.

See: https://ergast.com/mrd/methods/standings/

API Mapping

Structure of the raw response, renamed key names for flattening and dtypes for automatic type casting:

[
    {
        season: season <int>,
        round: round <int>,
        url: raceUrl <str>,
        raceName: raceName <str>,
        date: raceDate <Optional>,
        time: raceTime <Optional>,
        Circuit: {
            circuitId: circuitId <str>,
            url: circuitUrl <str>,
            circuitName: circuitName <str>,
            Location: {
                lat: lat <float>,
                long: long <float>,
                locality: locality <str>,
                country: country <str>
            }
        },
        PitStops: [
            {
                driverId: driverId <str>,
                stop: stop <int>,
                lap: lap <int>,
                time: time <Optional>,
                duration: duration <Optional>,
                Driver: {
                    driverId: driverId <str>,
                    permanentNumber: driverNumber <int>,
                    code: driverCode <str>,
                    url: driverUrl <str>,
                    givenName: givenName <str>,
                    familyName: familyName <str>,
                    dateOfBirth: dateOfBirth <Optional>,
                    nationality: driverNationality <str>
                },
                Constructors: [
                    {
                        constructorId: constructorIds <str>,
                        url: constructorUrls <str>,
                        name: constructorNames <str>,
                        nationality: constructorNationalities <str>
                    }
                ]
            }
        ]
    }
]

DataFrame Description

DataFrame column names and dtypes for automatic typecasting:

ErgastMultiResponse.description

season              <int>
round               <int>
raceUrl             <str>
raceName            <str>
raceDate       <Optional>
raceTime       <Optional>
circuitId           <str>
circuitUrl          <str>
circuitName         <str>
lat               <float>
long              <float>
locality            <str>
country             <str>

ErgastMultiResponse.content (contains data from subkey PitStops)

driverId                         <str>
stop                             <int>
lap                              <int>
time                        <Optional>
duration                    <Optional>
driverNumber                     <int>
driverCode                       <str>
driverUrl                        <str>
givenName                        <str>
familyName                       <str>
dateOfBirth                 <Optional>
driverNationality                <str>
constructorIds                 [<str>]
constructorUrls                [<str>]
constructorNames               [<str>]
constructorNationalities       [<str>]

Parameters:

season (Union[Literal['current'], int]) – select a season by its year (default: all, oldest first)
round (Union[Literal['last'], int]) – select a round by its number (default: all)
lap_number (Optional[int]) – select pit stops by a specific lap number (default: all)
stop_number (Optional[int]) – select pit stops by their stop number (default: all)
driver (Optional[str]) – select a driver by its driver id (default: all)
result_type (Optional[Literal['pandas', 'raw']]) – Overwrites the default result type
auto_cast (Optional[bool]) – Overwrites the default value for auto_cast
limit (Optional[int]) – Overwrites the default value for limit
offset (Optional[int]) – An offset into the result set for response paging. Defaults to 0 if not set. See also “Response Paging”, https://ergast.com/mrd/.

Return type:

Union[ErgastMultiResponse, ErgastRawResponse]

Returns:

ErgastMultiResponse or ErgastRawResponse, depending on the result_type parameter

Response Objects¶

class fastf1.ergast.interface.ErgastRawResponse(*, query_result, category, auto_cast, **kwargs)[source]¶

Provides the raw JSON-like response data from Ergast.

This class wraps a list and adds response information and paging (see ErgastResponseMixin).

This “raw” response does not actually contain the complete JSON response that the API provides. Instead, only the actual data part of the response is returned while metadata (version, query parameters, response length, …) are not included. But metadata is used internally to provide pagination and information that are implemented by the ErgastResponseMixin.

Parameters:

category – Reference to a category from fastf1.ergast.structure that describes the result data
auto_cast – Determines if values are automatically cast to the most appropriate data type from their original string representation

class fastf1.ergast.interface.ErgastSimpleResponse(*args, response_headers, query_filters, metadata, selectors, **kwargs)[source]¶

Provides simple Ergast result data in the form of a Pandas DataFrame.

This class wraps an ErgastResultFrame and adds response information and paging (see ErgastResponseMixin).

class fastf1.ergast.interface.ErgastMultiResponse(*args, response_description, response_data, category, subcategory, auto_cast, **kwargs)[source]¶

Provides complex Ergast result data in the form of multiple Pandas DataFrames.

This class additionally offers response information and paging (see ErgastResponseMixin).

Note: This object is usually not instantiated by the user. Instead, you should use one of the API endpoint methods that are provided by Ergast get data from the API.

Example:

>>> from fastf1.ergast import Ergast
>>> ergast = Ergast(result_type='pandas', auto_cast=True)
>>> result = ergast.get_race_results(season=2022)

# The description shows that the result includes data from two
# grand prix.
>>> result.description
   season  round  ... locality       country
0    2022      1  ...   Sakhir       Bahrain
1    2022      2  ...   Jeddah  Saudi Arabia

[2 rows x 13 columns]

# As expected, ``result.content`` contains two elements, one for each
# row of the description
>>> len(result.content)
2

# The first element contains all results from the first of the two
# grand prix.
>>> result.content[0]
    number  position  ... fastestLapAvgSpeedUnits  fastestLapAvgSpeed
0       16         1  ...                     kph             206.018
1       55         2  ...                     kph             203.501
2       44         3  ...                     kph             202.469
...
17      11        18  ...                     kph             202.762
18       1        19  ...                     kph             204.140
19      10        20  ...                     kph             200.189

[20 rows x 26 columns]

# The second element is incomplete and only contains the first 10
# positions of the second Grand Prix. This is because by default,
# every query on Ergast is limited to 30 result values. You can
# manually change this limit for each request though.
>>> result.content[1]
   number  position  ... fastestLapAvgSpeedUnits  fastestLapAvgSpeed
0       1         1  ...                     kph             242.191
1      16         2  ...                     kph             242.556
2      55         3  ...                     kph             241.841
...
7      10         8  ...                     kph             237.796
8      20         9  ...                     kph             239.562
9      44        10  ...                     kph             239.001

[10 rows x 26 columns]

Parameters:

response_description (dict) – Ergast response containing only the “descriptive” information (only data that is available in description)
response_data (list) – A list of the “content” data that has been split from the Ergast response (data that is available in content)
category (dict) – A category object from fastf1.ergast.structure that defines the main category.
subcategory (dict) – A category object from fastf1.ergast.structure that defines the subcategory which is the content data.
auto_cast (bool) – Flag that enables or disables automatic casting from the original string representation to the most suitable data type.

property description: ErgastResultFrame¶

An ErgastResultFrame that describes the data in content.

Each row of this ErgastResultFrame contains the descriptive information for one element in content.

property content: list[ErgastResultFrame]¶

A list of ErgastResultFrame that contain the main response data.

Descriptive data for each ErgastResultFrame is given in the corresponding row of description.

class fastf1.ergast.interface.ErgastResultFrame(data=None, *, category=None, response=None, auto_cast=True, **kwargs)[source]¶

Wraps a Pandas DataFrame. Additionally, this class can be initialized from Ergast response data with automatic flattening and type casting of the data.

Parameters:

data – Passed through to the DataFrame constructor (must be None if response is provided)
category (Optional[dict]) – Reference to a category from fastf1.ergast.structure that describes the result data
response (Optional[list]) – JSON-like response data from Ergast; used to generate data from an Ergast response (must be None if data is provided)
auto_cast (bool) – Determines if values are automatically cast to the most appropriate data type from their original string representation

class fastf1.ergast.interface.ErgastResponseMixin(*args, response_headers, query_filters, metadata, selectors, **kwargs)[source]¶

A Mixin class that adds support for pagination to Ergast response objects.

All Ergast response objects provide the methods that are implemented by this Mixin.

property total_results: int¶: Returns the total number of available results for the request associated with this response.

property is_complete: bool¶: Indicates if the response contains all available results for the request that is associated with it.

get_next_result_page()[source]¶

Returns the next page of results within the limit that was specified in the request that is associated with this response.

Raises:: ValueError – there is no result page after the current page
Return type:: Union[ErgastSimpleResponse, ErgastMultiResponse, ErgastRawResponse]

get_prev_result_page()[source]¶

Returns the previous page of results within the limit that was specified in the request that is associated with this response.

Raises:: ValueError – there is no result page before the current page
Return type:: Union[ErgastSimpleResponse, ErgastMultiResponse, ErgastRawResponse]

Exceptions¶

class fastf1.ergast.interface.ErgastError[source]¶: Base class for Ergast API errors.

class fastf1.ergast.interface.ErgastJsonError[source]¶: The response that was returned by the server could not be parsed.

class fastf1.ergast.interface.ErgastInvalidRequestError[source]¶: The server rejected the request because it was invalid.