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

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

  • Session*Date | datetime | The date and time at which the session is scheduled to start or was scheduled to start. * 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, 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

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

  • full session name: 'Practice 1', 'Practice 2', 'Practice 3', 'Sprint Qualifying', 'Sprint', '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’ is called ‘Sprint Qualifying’ only in the 2021 season. The event name will silently be corrected if you use ‘Sprint’/’S’ for the 2021 season or ‘Sprint Qualifying’/’SQ’ for the subsequent seasons.

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]

Bases: pandas.core.frame.DataFrame

This class implements a per-season event schedule.

This class is usually not instantiated directly. You should use 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.

Attributes:

base_class_view

For a nicer debugging experience; can view DataFrame through this property in various IDEs

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)

Get an Event by its name.

property base_class_view

For a nicer debugging experience; can view DataFrame through this property in various IDEs

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

Returns

Event

Raises

ValueError – The round does not exist in the event schedule

get_event_by_name(name)[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.

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.

Returns

Event

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

Bases: pandas.core.series.Series

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.

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

Parameters

year (int) – Championship year

Attributes:

date

Event race date (YYYY-MM-DD)

gp

Event round number

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)

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

Return the specified practice session.

property date

Event race date (YYYY-MM-DD)

This wraps self['EventDate'].strftime('%Y-%m-%d')

Deprecated since version 2.2: use Event.EventDate or Event['EventDate'] and use datetime.datetime.strftime() to format the desired string representation of the datetime object

property gp

Event round number

Deprecated since version 2.2: use Event.eventNumber or Event['eventNumber']

is_testing()[source]

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

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 (str or int) – see Session identifiers

Returns

str

Raises

ValueError – No matching session or invalid identifier

get_session_date(identifier)[source]

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

Parameters

identifier (str or int) – see Session identifiers

Returns

datetime.datetime

Raises

ValueError – No matching session or invalid identifier

get_session(identifier)[source]

Return a session from this event.

Parameters

identifier (str or int) – see Session identifiers

Returns

Session instance

Raises

ValueError – No matching session or invalid identifier

get_race()[source]

Return the race session.

Returns

Session instance

get_qualifying()[source]

Return the qualifying session.

Returns

Session instance

get_sprint()[source]

Return the sprint session.

Returns

Session instance

get_practice(number)[source]

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

Returns

Session instance