General Functions - fastf1

Accessing Events and Sessions

When using FastF1, you usually start by loading an event or a session. This can be done with one of the following functions:

fastf1.get_session(year, gp[, identifier, ...])

Create a Session object based on year, event name and session identifier.

fastf1.get_testing_session(year, ...)

Create a Session object for testing sessions based on year, test event number and session number.

fastf1.get_event(year, gp, *[, force_ergast])

Create an Event object for a specific season and gp.

fastf1.get_testing_session(year, ...)

Create a Session object for testing sessions based on year, test event number and session number.

fastf1.get_event_schedule(year, *[, ...])

Create an EventSchedule object for a specific season.

Caching

Caching should almost always be enabled to speed up the runtime of your scripts and to prevent exceeding the rate limit of api servers. FastF1 will print an annoyingly obnoxious warning message if you do not enable caching.

The following class-level functions are used to setup, enable and (temporarily) disable caching.

fastf1.Cache.enable_cache(cache_dir[, ...])

Enables the API cache.

fastf1.Cache.clear_cache(cache_dir[, deep])

Clear all cached data.

fastf1.Cache.disabled()

Returns a context manager object that creates a context within which the cache is temporarily disabled.

fastf1.Cache.set_disabled()

Disable the cache while keeping the configuration intact.

fastf1.Cache.set_enabled()

Enable the cache after it has been disabled with set_disabled().

General Functions - API Reference

Events API

fastf1.get_session(year, gp, identifier=None, *, force_ergast=False, event=None)[source]

Create a Session object based on year, event name and session identifier.

Note

This function will return a Session object, but it will not load any session specific data like lap timing, telemetry, … yet. For this, you will need to call load() on the returned object.

Deprecated since version 2.2: Creating Event objects (previously fastf1.core.Weekend) by not specifying an identifier has been deprecated. Use get_event() instead.

Deprecated since version 2.2: The argument event has been replaced with identifier to adhere to new naming conventions.

Deprecated since version 2.2: Testing sessions can no longer be created by specifying gp='testing'. Use get_testing_session() instead. There is no grace period for this change. This will stop working immediately with the release of v2.2!

To get a testing session, use get_testing_session().

Examples

Get the second free practice of the first race of 2021 by its session name abbreviation:

>>> get_session(2021, 1, 'FP2')

Get the qualifying of the 2020 Austrian Grand Prix by full session name:

>>> get_session(2020, 'Austria', 'Qualifying')

Get the 3rd session if the 5th Grand Prix in 2021:

>>> get_session(2021, 5, 3)
Parameters
  • year (int) – Championship year

  • gp (number or string) –

    Name as str or round number as int. If gp is a string, a fuzzy match will be performed on all events and the closest match will be selected. Fuzzy matching uses country, location, name and officialName of each event as reference.

    Some examples that will be correctly interpreted: ‘bahrain’, ‘australia’, ‘abudabi’, ‘monza’.

    See get_event_by_name() for some further remarks on the fuzzy matching.

  • identifier (str or int) – see Session identifiers

  • force_ergast (bool) – Always use data from the ergast database to create the event schedule

  • event – deprecated; use identifier instead

Return type

Session

fastf1.get_testing_session(year, test_number, session_number)[source]

Create a Session object for testing sessions based on year, test event number and session number.

Parameters
  • year (int) – Championship year

  • test_number (int) – Number of the testing event (usually at most two)

  • session_number (int) – Number of the session withing a specific testing event. Each testing event usually has three sessions.

Returns

Session

New in version 2.2.

fastf1.get_event(year, gp, *, force_ergast=False)[source]

Create an Event object for a specific season and gp.

To get a testing event, use get_testing_event().

Parameters
  • year (int) – Championship year

  • gp (int or str) – Name as str or round number as int. If gp is a string, a fuzzy match will be performed on all events and the closest match will be selected. Fuzzy matching uses country, location, name and officialName of each event as reference. Note that the round number cannot be used to get a testing event, as all testing event are round 0!

  • force_ergast (bool) – Always use data from the ergast database to create the event schedule

Returns

Event

New in version 2.2.

fastf1.get_testing_event(year, test_number)[source]

Create a fastf1.events.Event object for testing sessions based on year and test event number.

Parameters
  • year (int) – Championship year

  • test_number (int) – Number of the testing event (usually at most two)

Returns

Event

New in version 2.2.

fastf1.get_event_schedule(year, *, include_testing=True, force_ergast=False)[source]

Create an EventSchedule object for a specific season.

Parameters
  • year (int) – Championship year

  • include_testing (bool) – Include or exclude testing sessions from the event schedule.

  • force_ergast (bool) – Always use data from the ergast database to create the event schedule

Returns

EventSchedule

New in version 2.2.

Cache API

class fastf1.Cache[source]

Pickle and requests based API cache.

The parsed API data will be saved as a pickled object. Raw GET requests are cached in a sqlite db using the ‘requests-cache’ module.

Caching should almost always be enabled to speed up the runtime of your scripts and to prevent exceeding the rate limit of api servers. FastF1 will print an annoyingly obnoxious warning message if you do not enable caching.

The cache has two “stages”.

  • Stage 1: Caching of raw GET requests. This works for all requests. Cache control is employed to refresh the cached data periodically.

  • Stage 2: Caching of the parsed data. This saves a lot of time when running your scripts, as parsing of the data is computationally expensive. Stage 2 caching is only used for some api functions.

Most commonly, you will enable caching right at the beginning of your script:

>>> import fastf1
>>> fastf1.Cache.enable_cache('path/to/cache')  
# change cache directory to an exisitng empty directory on your machine
>>> session = fastf1.get_session(2021, 5, 'Q')
>>> # ...

Note that you should always enable caching except for very rare circumstances which are usually limited to doing core developement on FastF1.

Methods:

enable_cache(cache_dir[, ignore_version, ...])

Enables the API cache.

clear_cache(cache_dir[, deep])

Clear all cached data.

disabled()

Returns a context manager object that creates a context within which the cache is temporarily disabled.

set_disabled()

Disable the cache while keeping the configuration intact.

set_enabled()

Enable the cache after it has been disabled with set_disabled().

classmethod enable_cache(cache_dir, ignore_version=False, force_renew=False, use_requests_cache=True)[source]

Enables the API cache.

Parameters
  • cache_dir (str) – Path to the directory which should be used to store cached data. Path needs to exist.

  • ignore_version (bool) – Ignore if cached data was create with a different version of the API parser (not recommended: this can cause crashes or unrecognized errors as incompatible data may be loaded)

  • force_renew (bool) – Ignore existing cached data. Download data and update the cache instead.

  • use_requests_cache (bool) – Do caching of the raw GET and POST requests.

classmethod clear_cache(cache_dir, deep=False)[source]

Clear all cached data.

This deletes all cache files in the provided cache directory. Optionally, the requests cache is cleared too.

Can be called without enabling the cache first.

Deleting specific events or sessions is not supported but can be done manually (stage 2 cache). The cached data is structured by year, event and session. The structure is more or less self-explanatory. To delete specific events or sessions delete the corresponding folder within the cache directory. Deleting specific requests from the requests cache (stage 1) is not possible. To delete the requests cache only, delete the sqlite file in the root of the cache directory.

Parameters
  • cache_dir (str) – Path to the directory which is used to store cached data.

  • deep (bool) – Clear the requests cache (stage 1) too.

classmethod disabled()[source]

Returns a context manager object that creates a context within which the cache is temporarily disabled.

Example:

with Cache.disabled():
    # no caching takes place here
    ...

Note

The context manager is not multithreading-safe

classmethod set_disabled()[source]

Disable the cache while keeping the configuration intact.

This disables stage 1 and stage 2 caching!

You can enable the cache at any time using set_enabled()

Note

You may prefer to use disabled() to get a context manager object and disable the cache only within a specific context.

Note

This function is not multithreading-safe

classmethod set_enabled()[source]

Enable the cache after it has been disabled with set_disabled().

Warning

To enable the cache it needs to be configured properly. You need to call :func`enable_cache` once to enable the cache initially. set_enabled() and set_disabled() only serve to (temporarily) disable the cache for specific parts of code that should be run without caching.

Note

This function is not multithreading-safe