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’, ‘testing’.

  • 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 the 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 Schedule#

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

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

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

  • ‘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', 'R'

  • full session name: 'Practice 1', 'Practice 2', 'Practice 3', 'Sprint', 'Sprint Shootout', '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 ‘Sprint Qualifying’ is now always called ‘Sprint’. The event name will silently be corrected if you use ‘Sprint Qualifying’/’SQ’ instead of ‘Sprint’/’S’.

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)[source]#

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()[source]#

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

get_event_by_round(round)[source]#

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)[source]#

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) – Search only for exact query matches instead of using fuzzy search. For example, .get_event_by_name("British Grand Prix", strict_search=True) will return the event for the British Grand Prix, whereas .get_event_by_name("British", strict_search=True) will return None

Return type:

Event

class fastf1.events.Event(*args, year=None, **kwargs)[source]#

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 (Optional[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_practice(number)

Return the specified practice session.

is_testing()[source]#

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

Return type:

bool

get_session_name(identifier)[source]#

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)[source]#

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)[source]#

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()[source]#

Return the race session.

Return type:

Session

get_qualifying()[source]#

Return the qualifying session.

Return type:

Session

get_sprint()[source]#

Return the sprint session.

Return type:

Session

get_sprint_shootout()[source]#

Return the sprint shootout session.

Return type:

Session

get_practice(number)[source]#

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

Return type:

Session