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

result_type

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

auto_cast

bool

default:"True"

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

limit

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

circuit

str | None

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

constructor

str | None

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

driver

str | None

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

grid_position

int | None

Filter by starting grid position

results_position

int | None

Filter by finishing position

fastest_rank

int | None

Filter by fastest lap rank

status

str | None

Filter by finishing status

result_type

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

Override the default result type

auto_cast

bool | None

Override the default auto_cast setting

limit

int | None

Override the default limit

offset

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

season

Literal['current'] | int

required

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

round

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

season

Literal['current'] | int | None

Season year or ‘current’

round

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

season

Literal['current'] | int | None

Season year or ‘current’

round

Literal['last'] | int | None

Round number or ‘last’

driver

str | None

Filter by driver ID

standings_position

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

season

Literal['current'] | int

required

Season year or ‘current’

round

Literal['last'] | int

required

Round number or ‘last’

lap_number

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

season

Literal['current'] | int

required

Season year or ‘current’

round

Literal['last'] | int

required

Round number or ‘last’

stop_number

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

total_results

int

Total number of available results for this query

is_complete

bool

Whether the response contains all available results

Methods

get_next_result_page()

method

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

get_prev_result_page()

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

description

ErgastResultFrame

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

content

list[ErgastResultFrame]

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

total_results

int

Total number of available results

is_complete

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

total_results

int

Total number of available results

is_complete

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.

Core API

Data Access

Visualization

Utilities

​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

Build docs developers (and LLMs) love

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