Event Schedule - fastf1.events

The EventSchedule provides information about past and upcoming Formula 1 events.

An Event can be a race weekend or a testing event. Each event consists of multiple Session.

The event schedule objects are built on top of pandas’ pandas.DataFrame (event schedule) and pandas.Series (event). Therefore, the usual methods of these pandas objects can be used in addition to the special methods described here.

Event Schedule Data

The event schedule and each event provide the following information as DataFrame columns or Series values:

• RoundNumber | int | The number of the championship round. This is unique for race weekends, while testing events all share the round number zero.

• Country | str | The country in which the event is held.

• Location | str | The event location; usually the city or region in which the track is situated.

• OfficialEventName | str | The official event name as advertised, including sponsor names and stuff.

• EventName | str | A shorter event name usually containing the country or location but no no sponsor names. This name is required internally for proper api access.

• EventDate | pd.Timestamp | The events reference date and time. This is used mainly internally. Usually, this is the same as the date of the last session.

• EventFormat | str | The format of the event. One of ‘conventional’, ‘sprint’, ‘sprint_shootout’, ‘sprint_qualifying’, ‘testing’. See Event Formats

• Session* | str | The name of the session. One of ‘Practice 1’, ‘Practice 2’, ‘Practice 3’, ‘Qualifying’, ‘Sprint’, ‘Sprint Shootout’ or ‘Race’. Testing sessions are considered practice. * denotes the number of the session (1, 2, 3, 4, 5).

• Session*Date | pd.Timestamp | The date and time at which the session is scheduled to start or was scheduled to start as timezone-aware local timestamp. (Timezone-aware local timestamps are not available when the 'ergast' backend is used.) * denotes the number of the session (1, 2, 3, 4, 5).

• Session*DateUtc | pd.Timestamp | The date and time at which the session is scheduled to start or was scheduled to start as non-timezone-aware UTC timestamp. * denotes the number of the session (1, 2, 3, 4, 5).

• F1ApiSupport | bool | Denotes whether this session is supported by the official F1 API. Lap timing data and telemetry data can only be loaded if this is true.

Supported Seasons

FastF1 provides its own event schedule for the 2018 season and all later seasons. The schedule for all seasons before 2018 is built using data from the Ergast API. Only limited data is available for these seasons. Usage of the Ergast API can be enforced for all seasons by setting backend='ergast', in which case the same limitations apply for the more recent seasons too.

Exact scheduled starting times for all sessions: Supported starting with the 2018 season. Starting dates for sessions before 2018 (or when enforcing usage of the Ergast API) assume that each race weekend was held according to the ‘conventional’ schedule (Practice 1/2 on friday, Practice 3/Qualifying on Saturday, Race on Sunday). A starting date and time can only be provided for the race session. All other sessions are calculated from this and no starting times can be provided for these. These assumptions will be incorrect for certain events!

Testing events: Supported for the 2020 season and later seasons. Not supported if usage of the Ergast API is enforced.

Event Formats

• ‘conventional’: Practice 1, Practice 2, Practice 3, Qualifying, Race

• ‘sprint’: Practice 1, Qualifying, Practice 2, Sprint, Race

  This is the original sprint format that was used in some races in 2021 and 2022. The Qualifying on friday set the grid for the Sprint on saturday. The results from the Sprint set the grid for the Race on sunday.

• ‘sprint_shootout’: Practice 1, Qualifying, Sprint Shootout, Sprint, Race

  This format was used in 2023. The Qualifying on friday sets the grid for the main Race on sunday. The Sprint Shootout on saturday is held in similar fashion to a normal Qualifying session and sets the grid for the Sprint that takes place on saturday as well.

• ‘sprint_qualifying’: Practice 1, Sprint Qualifying, Sprint, Qualifying, Race

  This format is used starting from 2024. In general, it is similar to the previous ‘sprint_shootout’ format, but the order of the sessions was changed and ‘Sprint Shootout’ is renamed to ‘Sprint Qualifying’. This means that the Sprint Qualifying on friday is held in similar fashion to a normal Qualifying and sets the grid for the Sprint on saturday. The Qualifying later on saturday then sets the grid for the race on Sunday.

• ‘testing’: no fixed session order

  usually three practice sessions on three separate days

Session identifiers

Multiple event (schedule) related functions and methods make use of a session identifier to differentiate between the various sessions of one event. This identifier can currently be one of the following:

• session name abbreviation: 'FP1', 'FP2', 'FP3', 'Q', 'S', 'SS', 'SQ', 'R'

• full session name: 'Practice 1', 'Practice 2', 'Practice 3', 'Sprint', 'Sprint Shootout', 'Sprint Qualifying', 'Qualifying', 'Race'; provided names will be normalized, so that the name is case-insensitive

• number of the session: 1, 2, 3, 4, 5

Note that the old 'sprint' event format from 2021 and 2022 originally used the name ‘Sprint Qualifying’ before renaming these sessions to just ‘Sprint’. The official schedule for 2021 now lists all these sessions as ‘Sprint’ and FastF1 will therefore return all these session as ‘Sprint’. When querying for a specific session, FastF1 will also accept the ‘Sprint Qualifying’/’SQ’ identifier instead of only ‘Sprint’/’S’ for backwards compatibility.

Functions for accessing schedule data

The functions for accessing event schedule data are documented in General Functions - fastf1.

Data Objects

Overview

EventSchedule(*args[, year, force_default_cols])	This class implements a per-season event schedule.
Event(*args[, year])	This class represents a single event (race weekend or testing event).

API Reference

class fastf1.events.EventSchedule(*args, year=0, force_default_cols=False, **kwargs)

This class implements a per-season event schedule.

For detailed information about the information that is available for each event, see Event Schedule Data.

This class is usually not instantiated directly. You should use fastf1.get_event_schedule() to get an event schedule for a specific season.

Parameters:

• *args – passed on to pandas.DataFrame superclass

• year (int) – Championship year

• force_default_cols (bool) – Enforce that all default columns and only the default columns exist

• **kwargs – passed on to pandas.DataFrame superclass (except ‘columns’ which is unsupported for the event schedule)

New in version 2.2.

Methods:

is_testing()	Return True or False, depending on whether each event is a testing event.
get_event_by_round(round)	Get an Event by its round number.
get_event_by_name(name, *[, strict_search, ...])	Get an Event by its name.

is_testing()

Return True or False, depending on whether each event is a testing event.

get_event_by_round(round)

Get an Event by its round number.

Parameters:

round (int) – The round number

Raises:

ValueError – The round does not exist in the event schedule

Return type:

Event

get_event_by_name(name, *, strict_search=False, exact_match=False)

Get an Event by its name.

A fuzzy match is performed to find the event that best matches the given name. Fuzzy matching is performed using the country, location, name and officialName of each event. This is not guaranteed to return the correct result. You should therefore always check if the function actually returns the event you had wanted. To guarantee the function returns the event queried, toggle strict_search, which will only return an event if its event name matches (non case sensitive) the query string.

Warning

You should avoid adding common words to name to avoid false string matches. For example, you should rather use “Belgium” instead of “Belgian Grand Prix” as name.

Parameters:

• name (str) – The name of the event. For example, .get_event_by_name("british") and .get_event_by_name("silverstone") will both return the event for the British Grand Prix.

• strict_search (bool) – This argument is deprecated and planned for removal. Use the equivalent exact_match instead

• exact_match (bool) – Search only for exact query matches instead of using fuzzy search. For example, .get_event_by_name("British Grand Prix", exact_match=True) will return the event for the British Grand Prix, whereas .get_event_by_name("British", exact_match=True) will return None

Return type:

Event

class fastf1.events.Event(*args, year=None, **kwargs)

This class represents a single event (race weekend or testing event).

Each event consists of one or multiple sessions, depending on the type of event and depending on the event format.

For detailed information about the information that is available for each event, see Event Schedule Data.

This class is usually not instantiated directly. You should use fastf1.get_event() or similar to get a specific event.

Parameters:

year (int) – Championship year

Methods:

is_testing()	Return True or False, depending on whether this event is a testing event.
get_session_name(identifier)	Return the full session name of a specific session from this event.
get_session_date(identifier[, utc])	Return the date and time (if available) at which a specific session of this event is or was held.
get_session(identifier)	Return a session from this event.
get_race()	Return the race session.
get_qualifying()	Return the qualifying session.
get_sprint()	Return the sprint session.
get_sprint_shootout()	Return the sprint shootout session.
get_sprint_qualifying()	Return the sprint qualifying session.
get_practice(number)	Return the specified practice session.

is_testing()

Return True or False, depending on whether this event is a testing event.

Return type:

bool

get_session_name(identifier)

Return the full session name of a specific session from this event.

Examples

>>> import fastf1
>>> event = fastf1.get_event(2021, 1)
>>> event.get_session_name(3)
'Practice 3'
>>> event.get_session_name('Q')
'Qualifying'
>>> event.get_session_name('praCtice 1')
'Practice 1'

Parameters:

identifier – see Session identifiers

Raises:

ValueError – No matching session or invalid identifier

Return type:

str

get_session_date(identifier, utc=False)

Return the date and time (if available) at which a specific session of this event is or was held.

Parameters:

• identifier (Union[str, int]) – see Session identifiers

• utc – return a non-timezone-aware UTC timestamp

Raises:

ValueError – No matching session or invalid identifier

Return type:

Timestamp

get_session(identifier)

Return a session from this event.

Parameters:

identifier (Union[int, str]) – see Session identifiers

Raises:

ValueError – No matching session or invalid identifier

Return type:

Session

get_race()

Return the race session.

Return type:

Session

get_qualifying()

Return the qualifying session.

Return type:

Session

get_sprint()

Return the sprint session.

Return type:

Session

get_sprint_shootout()

Return the sprint shootout session.

Return type:

Session

get_sprint_qualifying()

Return the sprint qualifying session.

Return type:

Session

get_practice(number)

Return the specified practice session. :type number: int :param number: 1, 2 or 3 - Free practice session number

Return type:

Session