Ergast API - FastF1

Overview

The Ergast API provides access to historical Formula 1 data from 1950 onwards. FastF1’s Ergast interface wraps the Ergast Developer API and provides convenient methods for querying race results, driver standings, lap times, and more.

Ergast Class

The main interface to the Ergast API.

Constructor

from fastf1.ergast import Ergast

ergast = Ergast(
    result_type='pandas',  # or 'raw'
    auto_cast=True,
    limit=None
)

Parameters

Literal['raw', 'pandas']

default:"'pandas'"

Determines the default type of the returned result object:

'raw': Returns ErgastRawResponse with JSON-like data
'pandas': Returns ErgastSimpleResponse or ErgastMultiResponse with pandas DataFrames

bool

default:"True"

Whether to automatically cast values from their default string representation to more appropriate types (int, float, datetime, etc.)

int | None

default:"None"

Maximum number of results returned by the API. Defaults to 30 if not set. Maximum: 1000. See Ergast Response Paging.

Query Methods

All query methods support filtering by various parameters and return response objects with pagination support.

get_seasons()

Get a list of seasons.

result = ergast.get_seasons(
    circuit='monaco',
    driver='alonso'
)

Parameters

str | None

Filter by circuit ID (e.g., ‘monaco’, ‘silverstone’)

str | None

Filter by constructor ID (e.g., ‘mclaren’, ‘ferrari’)

str | None

Filter by driver ID (e.g., ‘alonso’, ‘hamilton’)

int | None

Filter by starting grid position

int | None

Filter by finishing position

int | None

Filter by fastest lap rank

str | None

Filter by finishing status

Literal['pandas', 'raw'] | None

Override the default result type

bool | None

Override the default auto_cast setting

int | None

Override the default limit

int | None

Offset into the result set for pagination (default: 0)

Returns

ErgastSimpleResponse or ErgastRawResponse depending on result_type

get_race_schedule()

Get the race schedule for one or more seasons.

result = ergast.get_race_schedule(season=2023)

Parameters

Literal['current'] | int

required

Season year (e.g., 2023) or ‘current’

Literal['last'] | int | None

Round number or ‘last’

Additional parameters: same as get_seasons() (circuit, constructor, driver, etc.)

get_driver_info()

Get driver information.

result = ergast.get_driver_info(
    season=2023,
    driver='verstappen'
)

Parameters

Literal['current'] | int | None

Season year or ‘current’

Literal['last'] | int | None

Round number or ‘last’

Additional parameters: same as get_seasons()

get_constructor_info()

Get constructor (team) information.

result = ergast.get_constructor_info(
    season=2023,
    constructor='red_bull'
)

Parameters: same as get_driver_info()

get_circuits()

Get circuit information.

result = ergast.get_circuits(season=2023)

Parameters: similar to get_driver_info() (no circuit parameter)

get_finishing_status()

Get finishing status codes and descriptions.

result = ergast.get_finishing_status(season=2023)

Parameters: same as get_seasons()

get_race_results()

Get race results for one or multiple races.

result = ergast.get_race_results(
    season=2023,
    round=5
)

Parameters: same as get_race_schedule()

Returns

ErgastMultiResponse or ErgastRawResponse - contains results for multiple races if filters match multiple events

get_qualifying_results()

Get qualifying results.

result = ergast.get_qualifying_results(
    season=2023,
    round=5
)

Parameters: same as get_race_schedule()

Returns

ErgastMultiResponse or ErgastRawResponse

get_sprint_results()

Get sprint race results.

result = ergast.get_sprint_results(
    season=2023,
    round=4
)

Parameters: same as get_race_schedule()

Returns

ErgastMultiResponse or ErgastRawResponse

get_driver_standings()

Get driver championship standings.

result = ergast.get_driver_standings(
    season=2023,
    round=5
)

Parameters

Literal['current'] | int | None

Season year or ‘current’

Literal['last'] | int | None

Round number or ‘last’

str | None

Filter by driver ID

int | None

Filter by standings position

Additional parameters: circuit, constructor, grid_position, etc.

Returns

ErgastMultiResponse or ErgastRawResponse

get_constructor_standings()

Get constructor championship standings.

result = ergast.get_constructor_standings(
    season=2023,
    round=5
)

Parameters: similar to get_driver_standings() with standings_position filter

Returns

ErgastMultiResponse or ErgastRawResponse

get_lap_times()

Get lap times for a specific lap.

result = ergast.get_lap_times(
    season=2023,
    round=5,
    lap_number=10
)

Parameters

Literal['current'] | int

required

Season year or ‘current’

Literal['last'] | int

required

Round number or ‘last’

int | None

Specific lap number (if not provided, returns all laps)

Additional parameters: driver, constructor, etc.

Returns

ErgastMultiResponse or ErgastRawResponse

get_pit_stops()

Get pit stop data.

result = ergast.get_pit_stops(
    season=2023,
    round=5,
    stop_number=1
)

Parameters

Literal['current'] | int

required

Season year or ‘current’

Literal['last'] | int

required

Round number or ‘last’

int | None

Filter by pit stop number (1st stop, 2nd stop, etc.)

Additional parameters: driver, constructor, etc.

Returns

ErgastMultiResponse or ErgastRawResponse

Response Objects

All Ergast query methods return response objects that wrap the data and provide pagination support.

ErgastSimpleResponse

Wraps a pandas DataFrame with additional response metadata.

Properties

int

Total number of available results for this query

bool

Whether the response contains all available results

Methods

method

Returns the next page of results. Raises ValueError if no more pages exist.

method

Returns the previous page of results. Raises ValueError if already at the first page.

ErgastMultiResponse

Wraps multiple pandas DataFrames for queries that return data about multiple races/events.

Properties

ErgastResultFrame

DataFrame describing each element in content (one row per race/event)

list[ErgastResultFrame]

List of DataFrames, one for each race/event. Each contains the detailed data (e.g., all driver results for that race).

int

Total number of available results

bool

Whether the response contains all available results

Methods

Same pagination methods as ErgastSimpleResponse

ErgastRawResponse

Wraps a list of JSON-like dictionaries with raw API response data.

Properties

int

Total number of available results

bool

Whether the response contains all available results

Methods

Same pagination methods as ErgastSimpleResponse

ErgastResultFrame

A specialized pandas DataFrame that contains Ergast response data with automatic type casting and flattening.

Examples

Basic Usage

from fastf1.ergast import Ergast

ergast = Ergast()

# Get 2023 season race schedule
schedule = ergast.get_race_schedule(season=2023)
print(schedule)

# Get race results for Monaco 2023
results = ergast.get_race_results(season=2023, round=6)
print(results.description)  # Race info
print(results.content[0])   # Driver results

# Get driver standings after round 10
standings = ergast.get_driver_standings(season=2023, round=10)
print(standings.description)
print(standings.content[0])

Filtering

# Get all seasons where Hamilton won races
seasons = ergast.get_seasons(
    driver='hamilton',
    results_position=1
)

# Get all pole positions at Monaco
poles = ergast.get_qualifying_results(
    circuit='monaco',
    results_position=1,
    limit=100
)

Pagination

# Get first page of results (default limit: 30)
results = ergast.get_race_results(season=2023)

# Check if more pages exist
if not results.is_complete:
    # Get next page
    next_page = results.get_next_result_page()
    print(f"Total results: {results.total_results}")

Raw Response

# Get raw JSON-like data instead of DataFrames
ergast_raw = Ergast(result_type='raw')
raw_data = ergast_raw.get_race_results(season=2023, round=1)

# raw_data is a list of dictionaries
for race in raw_data:
    print(race['raceName'])

Notes

The Ergast API has rate limits:

4 requests per second (enforced by FastF1)
200 requests per hour

Requests are automatically cached to reduce API calls. Enable caching with fastf1.Cache.enable_cache().

The Ergast API is a community-provided service. Be respectful of rate limits and consider caching to minimize requests.

​Overview

​Ergast Class

​Constructor

​Parameters

​Query Methods

​get_seasons()

​Parameters

​Returns

​get_race_schedule()

​Parameters

​get_driver_info()

​Parameters

​get_constructor_info()

​get_circuits()

​get_finishing_status()

​get_race_results()

​Returns

​get_qualifying_results()

​Returns

​get_sprint_results()

​Returns

​get_driver_standings()

​Parameters

​Returns

​get_constructor_standings()

​Returns

​get_lap_times()

​Parameters

​Returns

​get_pit_stops()

​Parameters

​Returns

​Response Objects

​ErgastSimpleResponse

​Properties

​Methods

​ErgastMultiResponse

​Properties

​Methods

​ErgastRawResponse

​Properties

​Methods

​ErgastResultFrame

​Examples

​Basic Usage

​Filtering

​Pagination

​Raw Response

​Notes

​See Also

Overview

Ergast Class

Constructor

Parameters

Query Methods

get_seasons()

Parameters

Returns

get_race_schedule()

Parameters

get_driver_info()

Parameters

get_constructor_info()

get_circuits()

get_finishing_status()

get_race_results()

Returns

get_qualifying_results()

Returns

get_sprint_results()

Returns

get_driver_standings()

Parameters

Returns

get_constructor_standings()

Returns

get_lap_times()

Parameters

Returns

get_pit_stops()

Parameters

Returns

Response Objects

ErgastSimpleResponse

Properties

Methods

ErgastMultiResponse

Properties

Methods

ErgastRawResponse

Properties

Methods

ErgastResultFrame

Examples

Basic Usage

Filtering

Pagination

Raw Response

Notes

See Also