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, ...[, backend])

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

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

Create an Event object for a specific season and gp.

fastf1.get_events_remaining([dt, ...])

Create an EventSchedule object for remaining season.

fastf1.get_testing_session(year, ...[, backend])

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.

Requests and Caching

All HTTP requests that are performed by FastF1 go through its caching and rate limiting system.

Caching is enabled by default in FastF1 and most of the time, you do not need to worry about caching at all. It will simply happen automatically in the background and speed up your programs. Disabling the cache is highly discouraged and will generally slow down your programs.

Rate limits are applied at all times. Requests that can be served from the cache do not count towards any rate limits. Having the cache enabled can therefore virtually increase the rate limits.

When rate limits are exceeded, FastF1 will either…

  • throttle the rate of requests, if small delays are sufficient to stay within the limit (soft rate limit)

  • raise a fastf1.RateLimitExceededError (hard rate limit)

General Functions - API Reference

Event and Session API

fastf1.get_session(year, gp, identifier=None, *, backend=None, force_ergast=False)[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.

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 of the 5th Grand Prix in 2021:

>>> get_session(2021, 5, 3)
Parameters:

  • year (int) – Championship year

  • gp (Union[str, int]) –

    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’.

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

  • backend (Optional[Literal['fastf1', 'f1timing', 'ergast']]) –

    select a specific backend as data source, options: - 'fastf1': FastF1’s own backend, full support for 2018 to now

    • 'f1timing': uses data from the F1 live timing API, sessions for which no timing data is available are not listed (supports 2018 to now)

    • 'ergast': uses data from Ergast, no local times are available, no information about availability of f1 timing data is available (supports 1950 to now)

    When no backend is specified, 'fastf1' is used as a default and the other backends are used as a fallback in case the default is not available.

    For seasons older than 2018 'ergast' is always used.

  • force_ergast (bool) – [Deprecated, use backend='ergast'] Always use data from the ergast database to create the event schedule

Return type:

Session

fastf1.get_testing_session(year, test_number, session_number, *, backend=None)[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 within a specific testing event. Each testing event usually has three sessions.

  • backend (Optional[Literal['fastf1', 'f1timing']]) –

    select a specific backend as data source, options:

    • 'fastf1': FastF1’s own backend, full support for 2018 to now

    • 'f1timing': uses data from the F1 live timing API, sessions

      for which no timing data is available are not listed (supports 2018 to now)

    When no backend is specified, 'fastf1' is used as a default and f1timing is used as a fallback in case the default is not available.

Return type:

Session

New in version 2.2.

fastf1.get_event(year, gp, *, backend=None, force_ergast=False, strict_search=False, exact_match=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 (Union[int, 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!

  • backend (Optional[Literal['fastf1', 'f1timing', 'ergast']]) –

    select a specific backend as data source, options:

    • 'fastf1': FastF1’s own backend, full support for 2018 to now

    • 'f1timing': uses data from the F1 live timing API, sessions for which no timing data is available are not listed (supports 2018 to now)

    • 'ergast': uses data from Ergast, no local times are available, no information about availability of f1 timing data is available (supports 1950 to now)

    When no backend is specified, 'fastf1' is used as a default and the other backends are used as a fallback in case the default is not available.

    For seasons older than 2018 'ergast' is always used.

  • force_ergast (bool) – [Deprecated, use backend='ergast'] Always use data from the ergast database to create the event schedule

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

  • exact_match (bool) – Match precisely the query, or default to fuzzy search. If no event is found with exact_match=True, the function will return None

Return type:

Event

New in version 2.2.

fastf1.get_events_remaining(dt=None, *, include_testing=True, backend=None, force_ergast=False)[source]

Create an EventSchedule object for remaining season.

Parameters:

  • dt (Optional[datetime]) – Optional DateTime to get events after.

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

  • backend (Optional[Literal['fastf1', 'f1timing', 'ergast']]) –

    select a specific backend as data source, options:

    • 'fastf1': FastF1’s own backend, full support for 2018 to now

    • 'f1timing': uses data from the F1 live timing API, sessions for which no timing data is available are not listed (supports 2018 to now)

    • 'ergast': uses data from Ergast, no local times are available, no information about availability of f1 timing data is available (supports 1950 to now)

    When no backend is specified, 'fastf1' is used as a default and the other backends are used as a fallback in case the default is not available.

    For seasons older than 2018 'ergast' is always used.

  • force_ergast (bool) – [Deprecated, use backend='ergast'] Always use data from the ergast database to create the event schedule

Return type:

EventSchedule

New in version 2.3.

fastf1.get_testing_event(year, test_number, *, backend=None)[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)

  • backend (Optional[Literal['fastf1', 'f1timing']]) –

    select a specific backend as data source, options:

    • 'fastf1': FastF1’s own backend, full support for 2018 to now

    • 'f1timing': uses data from the F1 live timing API, sessions for which no timing data is available are not listed (supports 2018 to now)

    When no backend is specified, 'fastf1' is used as a default and f1timing is used as a fallback in case the default is not available.

Return type:

Event

New in version 2.2.

fastf1.get_event_schedule(year, *, include_testing=True, backend=None, 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.

  • backend (Optional[Literal['fastf1', 'f1timing', 'ergast']]) –

    select a specific backend as data source, options:

    • 'fastf1': FastF1’s own backend, full support for 2018 to now

    • 'f1timing': uses data from the F1 live timing API, sessions for which no timing data is available are not listed (supports 2018 to now)

    • 'ergast': uses data from Ergast, no local times are available, no information about availability of f1 timing data is available (supports 1950 to now)

    When no backend is specified, 'fastf1' is used as a default and the other backends are used as a fallback in case the default is not available.

    For seasons older than 2018 'ergast' is always used.

  • force_ergast (bool) – [Deprecated, use backend='ergast'] Always use data from the ergast database to create the event schedule

Return type:

EventSchedule

New in version 2.2.

Cache API

class fastf1.Cache[source]

Pickle and requests based API cache.

Fast-F1 will per default enable caching. While this can be disabled, it should almost always be left enabled to speed up the runtime of your scripts and to prevent exceeding the rate limit of api servers.

The default cache directory is defined, in order of precedence, in one of the following ways:

  1. A call to enable_cache()

  2. The value of the environment variable FASTF1_CACHE

  3. An OS dependent default cache directory

See below for more information on default cache directories.

The following class-level functions are used to set up, 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.get_cache_info()

Returns information about the cache directory and its size.

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().

fastf1.Cache.offline_mode(enabled)

Enable or disable offline mode.

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

Requests that can be served from the cache do not count towards any API rate limits.

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.

You can explicitly configure right at the beginning of your script:

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

An alternative way to set the cache directory is to configure an environment variable FASTF1_CACHE. However, this value will be ignored if Cache.enable_cache() is called.

If no explicit location is provided, Fast-F1 will use a default location depending on operating system.

  • Windows: %LOCALAPPDATA%\Temp\fastf1

  • macOS: ~/Library/Caches/fastf1

  • Linux: ~/.cache/fastf1 if ~/.cache exists otherwise ~/.fastf1

Cached data can be deleted at any time to reclaim disk space. However, this also means you will have to redownload the same data again if you need which will lead to reduced performance.

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().

offline_mode(enabled)

Enable or disable offline mode.

get_cache_info()

Returns information about the cache directory and its size.
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 created 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=None, deep=False)[source]

Clear all cached data.

Deletes all files in the cache directory. By default, it will clear the default cache directory. However, if a cache directory is provided as an argument this will be cleared instead. Optionally, the requests cache can be 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

classmethod offline_mode(enabled)[source]

Enable or disable offline mode.

In this mode, no actual requests will be sent and only cached data is returned. This can be useful for freezing the state of the cache or working with an unstable internet connection.

Parameters:

enabled (bool) – sets the state of offline mode to ‘enabled’ (True) or ‘disabled’ (False)

classmethod get_cache_info()[source]

Returns information about the cache directory and its size.

If the cache is not configured, None will be returned for both the cache path and the cache size.

Return type:

tuple[Optional[str], Optional[int]]

Returns:

A tuple of (path, size) if the cache is configured, else (None, None). The cache size is given in bytes.

class fastf1.RateLimitExceededError[source]

Raised if a hard rate limit is exceeded.

Configure Logging Verbosity

All parts of FastF1 generally log at the log level ‘INFO’. The reason for this is that many data loading processes take multiple seconds to complete. Logging is used to give progress information here as well as for showing warnings and non-terminal errors.

The logging level for FastF1 can be easily customized:

import fastf1

fastf1.set_log_level('WARNING')

# ... your code  here ... #

The available levels are (in order of increasing severity): DEBUG, INFO, WARNING, ERROR and CRITICAL.

fastf1.set_log_level(level)[source]

Set the log level for all parts of FastF1.

When setting the log level for FastF1, only messages with this level or with a higher level will be shown.

Parameters:

level (Union[str, int]) – Either a log level from the logging module (e.g. logging.INFO) or the level as a string (e.g. ‘WARNING’).

For more information see Logging - fastf1.logger.