Skip to main content
The events module is the gateway to discovering and navigating Formula 1 calendar data. It provides a type-safe API for event schedules, session timings, and metadata across multiple seasons. The module is the foundation for all data discovery operations in tif1.

Overview

The events module provides a complete set of functions and classes. These list the Formula 1 events and sessions on the calendar of a given year. They do not check which data the TracingInsights CDN holds. This module is the primary entry point for event discovery and session navigation in tif1. It enables workflows for data analysis, visualization, and automation.

Core Capabilities

Use the events API to:
  • Query season schedules: Retrieve complete event calendars for any F1 season (1950-present; local session times and testing events from 2018). Each calendar carries full metadata, including event names, locations, countries, dates, and formats
  • Discover scheduled sessions: List the sessions of each event from the schedule. Sessions include Practice 1-3, Qualifying, Sprint Shootout, Sprint Qualifying, Sprint, and Race
  • Access event metadata: Get detailed information about each Grand Prix. The information includes official event names (with sponsors), circuit locations, round numbers, event dates, and weekend formats
  • Navigate flexibly: Use fuzzy matching to find events by partial names, abbreviations, circuit names, or round numbers. Exact string matches are not required
  • Work with timezone-aware data: Access session start times in local circuit time with a UTC offset. Convert them to UTC for time-based analysis and scheduling
  • Handle different event formats: Work with conventional race weekends (3 practice sessions), sprint weekends, and pre-season testing events. Sprint weekend formats vary by year
  • Use pandas integration: Work with DataFrame and Series interfaces enhanced with domain-specific methods for F1 data navigation
  • Benefit from caching: The raw schedule data is cached in memory after the first load. Later queries use no network until the schedule_ttl_hours window of a live season expires

Architecture & Design Philosophy

The events module is built on several key design principles:
  1. Performance-First: The raw schedule is loaded once and kept in memory. Past seasons come from vendored JSON files; the current and future seasons are fetched from the live f1schedule repository and cached for schedule_ttl_hours.
  2. Pandas Integration: All data structures extend pandas DataFrame and Series, providing familiar interfaces while adding F1-specific methods. This enables integration with the broader pandas ecosystem.
  3. Flexible Querying: Multiple lookup methods exist: by round number, by name, or by fuzzy match. Each use case, programmatic or interactive, has a suitable method.
  4. Type Safety: The public functions carry type hints, so IDE autocomplete and static type checkers know what they return.
  5. Graceful Degradation: The module handles missing data, network failures, and edge cases gracefully. It provides clear error messages and fallback behaviors.

Data Sources & Availability

Schedule data is sourced from two locations:
  • Live f1schedule file: The current and future seasons are fetched from the theOehrly/f1schedule GitHub repository (raw.githubusercontent.com). FastF1 reads the same file. The raw file is cached in SQLite for schedule_ttl_hours (default 6, TIF1_SCHEDULE_TTL_HOURS). After that window the cached copy is still served, and a background thread fetches the new file; the next lookup uses it. A rescheduled or cancelled round shows up with that refresh. Years without a vendored file use the same path
  • Vendored JSON files: The seasons 2018-2026 are packaged with tif1. Past seasons are served from them without a network request. When the fetch fails or offline_mode is on, the current season uses the last cached copy, even an expired one. Without a cached copy, it uses its vendored file
Supported years: 1950 to the current season. Seasons from 2018 come from the f1schedule calendar. Earlier seasons (and backend="ergast" for any season) come from the Ergast race table packaged with tif1. Those schedules carry estimated practice times and UTC session times only. Every schedule also carries CircuitId, CircuitName, CircuitLatitude, CircuitLongitude, EventUrl and CircuitUrl after fastf1’s columns. Refer to Historical data. The schedule data includes:
  • All championship Grand Prix events
  • Pre-season testing events (optional, can be filtered)
  • Sprint weekend events with correct session formats
  • Session names and availability
  • Event metadata (names, locations, countries, dates, formats)
  • Session timing information (local time with the UTC offset of the circuit)
All event discovery functions use caching to minimize network requests. Schedule data is loaded once per Python process and reused by later queries. A live season is loaded again after schedule_ttl_hours. get_event_schedule() still builds a new DataFrame on each call (a few milliseconds), so keep the result when a loop needs it.
The events module shows what data should be available based on the official F1 calendar. Actual data availability in the CDN may vary. Always handle DataNotFoundError exceptions when loading session data, because some sessions may have incomplete or missing data.

Core Functions

get_events

Retrieves the complete EventSchedule DataFrame containing all Grand Prix events for the specified Formula 1 season. This is the primary entry point for discovering what events occurred (or are scheduled) in a given year. The function returns an EventSchedule object. This object is a specialized pandas DataFrame subclass with methods for event lookup and filtering. Each row in the DataFrame represents a single Grand Prix event. The row carries metadata including event names, locations, dates, session schedules, and format information. Parameters:
int
required
The Formula 1 season year to query. A year without schedule data returns an empty EventSchedule. No exception is raised.Supported years: 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025, 2026
Returns:
EventSchedule
A pandas DataFrame subclass containing all events for the specified year. The DataFrame includes the following columns:
  • EventName: Official short name (for example, “Belgian Grand Prix”)
  • Location: Circuit or venue name (for example, “Spa-Francorchamps”)
  • OfficialEventName: Full official event title with sponsors
  • RoundNumber: Championship round number (1-indexed; 0 for testing rows)
  • Country: Country where the event takes place
  • EventDate: Main event date (typically race day), datetime64
  • EventFormat: Format type (“conventional”, “sprint”, “sprint_shootout”, “sprint_qualifying”, or “testing”)
  • Session1, Session2, …: Names of the scheduled sessions
  • Session1Date, Session2Date, …: Local session start times with a fixed UTC offset
  • Session1DateUtc, Session2DateUtc, …: Naive datetime64 start times in UTC (the local time minus GmtOffset)
  • F1ApiSupport, GmtOffset: API support flag and the UTC offset of the circuit (for example, “+02:00”)
The EventSchedule object also provides specialized methods like get_event_by_round() and get_event_by_name() for convenient event lookup.
Raises:
  • InvalidDataError: If the schedule data is malformed or cannot be parsed
A year without schedule data does not raise: when the repository has no file for it, the function returns an empty EventSchedule. A failed fetch logs a warning and falls back to the cached or vendored schedule. Behavior & Implementation Details:
  • Caching: The raw schedule data is cached in memory after the first request. Later calls for the same year make no network requests until schedule_ttl_hours have passed for a live season, but each call builds a new EventSchedule.
  • Data Source: The current and future seasons come from the live theOehrly/f1schedule repository (raw.githubusercontent.com, the same file FastF1 reads). tif1 fetches the file again once the cached copy is older than schedule_ttl_hours (default 6). Past seasons come from the vendored JSON files (2018 onwards); earlier years fall back to the repository.
  • Testing Events: By default, get_events() includes all events including pre-season testing. Testing rows have RoundNumber 0 and come after the race weekends. Use get_event_schedule(year, include_testing=False) to exclude them.
  • Performance: A call takes a few milliseconds for vendored or cached data, because it builds one Event per row. Only the first fetch of a live season into an empty cache directory adds the network time. A later refresh runs in a background thread while the cached copy is served.
Example Usage:
Advanced Example - Analyzing Event Distribution:
Use get_events() to work with the complete season schedule as a DataFrame. For a single event by name, get_event_by_name() is the quickest lookup, because it does not build the schedule.

get_sessions

Returns the list of scheduled session names for a specific Grand Prix event. The list comes from the schedule, not from the CDN. It does not confirm that data exists. Session availability varies by event format:
  • Conventional weekends: Typically include Practice 1, Practice 2, Practice 3, Qualifying, and Race
  • Sprint weekends: May include Practice 1, Sprint Qualifying, Sprint, Qualifying, and Race (format varies by year)
  • Testing events: List their test days as “Practice 1”, “Practice 2”, and “Practice 3”
Parameters:
int
required
The Formula 1 season year. A year without schedule data returns the conventional list (Practice 1-3, Qualifying, Race).
str
required
The event name (for example, “Belgian Grand Prix”). A name that is not an exact EventName resolves like get_event_by_name(). The lookup tries a case-insensitive name, then the alias table (“Silverstone”, “Spa”), then fuzzy matching.An empty name returns the conventional list (Practice 1-3, Qualifying, Race). A name that matches no event raises EventNotFoundError, as get_event_by_name() does.
Returns:
list[str]
An ordered list of session names available for the specified event. Sessions are returned in chronological order (Practice 1 → Practice 2 → … → Race).Common session names:
  • "Practice 1", "Practice 2", "Practice 3"
  • "Qualifying"
  • "Sprint Qualifying", "Sprint Shootout" (sprint weekend qualifying)
  • "Sprint" (sprint race)
  • "Race" (main Grand Prix)
Raises:
  • EventNotFoundError: If the name matches no event of the season (a fuzzy score below 70), for example get_sessions(2025, "xyz")
  • EventNotInSeasonError: If an alias names an event that is not on the calendar of that year, for example get_sessions(2021, "Suzuka")
  • InvalidDataError: If the schedule data is malformed
Behavior & Implementation Details:
  • Name Resolution: An exact EventName is a direct lookup. Other names resolve like get_event_by_name(), so “British” and “Silverstone” give the 2021 sprint weekend sessions. Fuzzy matching logs a Correcting user input warning unless exactly one event contains the query in its name, official name, location, or country.
  • Caching: Session lists are cached per season and query after the first call. Later calls for the same name are a dictionary lookup.
  • Data Availability: The returned list shows the scheduled sessions. A listed session can still lack some data types (laps, telemetry, etc.) on the CDN.
  • Fallback List: An empty name, or a year without schedule data, returns the conventional five-session list. No exception is raised.
Example Usage:
Advanced Example - Session Availability Analysis:
Practical Example - Loading All Sessions for an Event:
The presence of a session in the returned list does not guarantee that all data types are available. Some sessions may have lap data but no telemetry, or vice versa. Always handle potential DataNotFoundError exceptions when loading session data.

get_event

Retrieves an Event object for a specific Grand Prix by either name or round number. This event lookup function accepts multiple identifier formats and provides fuzzy matching for event names. The returned Event object is a pandas Series subclass. It contains all event metadata. It also provides methods for accessing sessions, session timings, and other event-specific information. Parameters:
int
required
The Formula 1 season year (2018-2026).
int | str
required
The Grand Prix identifier. Can be either:Round number (int):
  • Championship round number (1-indexed)
  • Example: 12 for the 12th race of the season
  • Must be a round of the season. Round 0 (testing) and out-of-range rounds raise ValueError
Event name (str):
  • Full official name: "Belgian Grand Prix"
  • Partial name: "Belgian"
  • Circuit, city, or country alias: "Spa", "Monza", "Interlagos", "USA"
  • Case-insensitive: "belgian grand prix", "BELGIAN GP"
  • Pass round numbers as int. A digit string such as "12" goes through name matching
bool
default:"False"
Controls the string matching behavior when gp is a string:
  • False (default): Uses fuzzy matching to find the best match. Tolerates typos, partial names, and case variations. A name that resembles no event gives None.
  • True: Requires the full event name. The comparison ignores case. Use this for precise control or to avoid ambiguous matches.
Note: This parameter is ignored when gp is an integer (round number).
Returns:
Event | None
An Event object (pandas Series subclass) containing event metadata and methods for session access.Returns None when no event matches the name. An exact-match miss gives None. So does a fuzzy score below 70 (“Moon GP”) or an alias of an event not held that year (“Suzuka” in 2021). tif1 logs the reason for the last two at INFO level. get_event() does not raise for these names. get_event_by_name() raises EventNotFoundError or EventNotInSeasonError for the same input.
Raises:
  • ValueError: If the round number is 0 or out of range for the season
  • InvalidDataError: If the schedule data is malformed
Behavior & Implementation Details:
  • Matching Order: An exact (case-insensitive) name match comes first. Then the alias table EVENT_NAME_ALIASES maps circuit, city, and country names (“Spa”, “Silverstone”, “USA”) to events. Last, a fuzzy match runs on the location, country, and names of each event.
  • Per-Season Aliases: Aliases resolve against the calendar of the requested year. “Barcelona” is the Spanish Grand Prix in 2024 and the Barcelona Grand Prix in 2026. exact_match=True ignores aliases.
  • Fuzzy Score Floor: With exact_match=False, a fuzzy match needs a score of at least 70 (rapidfuzz ratio, 0-100). A typo such as “Monacco” resolves and logs a warning such as Correcting user input 'Monacco' to 'Monaco Grand Prix'. A name such as “xyz” or “Moon GP” gives None. Check event['EventName'] before use.
  • Round Number Lookup: When gp is an integer, the function selects the row with that RoundNumber.
  • Event Truth Value: An Event is a pandas Series. Test it with event is not None, never with if event: (that raises ValueError).
Example Usage:
Advanced Example - Event Comparison:
Practical Example - Flexible Event Lookup:
For programmatic access with a known round number, use the integer form. It is reliable because no name matching takes place. For user-facing applications or interactive use, the fuzzy string matching provides a good user experience.

get_event_by_round

Retrieves an Event object by its championship round number. When the round number is known, this is the most reliable lookup method. It selects the row by RoundNumber, without any string matching or fuzzy logic. Round numbers are 1-indexed and correspond to the official FIA Formula 1 World Championship round numbering. For example, the first race of the season is round 1, the second is round 2, and so on. Round numbers are consistent within a season. They may vary between seasons for the same Grand Prix. For example, Monaco might be round 5 in one year and round 7 in another. Parameters:
int
required
The Formula 1 season year (2018-2026). Must be a year with available schedule data.
int
required
The championship round number (1-indexed). Must be within the valid range for the specified season.Valid ranges by season:
  • Most seasons: 21 to 24 rounds
  • 2020 (COVID-affected): 1-17 rounds
  • Check len(tif1.get_event_schedule(year, include_testing=False)) for the exact count
Note: len(tif1.get_events(year)) also counts the testing rows (RoundNumber 0), so it can exceed the last round.
Returns:
Event
An Event object (pandas Series subclass) containing all event metadata and methods for session access. The Event object provides dictionary-style access to fields like EventName, Location, Country, RoundNumber, EventDate, EventFormat, and session information.
Raises:
  • ValueError: If the round number is 0 or out of range for the specified season. For example, a request for round 25 in a season with 22 rounds raises this error. A year without schedule data also raises ValueError.
Behavior & Implementation Details:
  • Performance: This lookup does no name matching. It builds the season schedule on each call (a few milliseconds). In a loop, call schedule.get_event_by_round() on one schedule.
  • Reliability: Round numbers are unambiguous and do not require any fuzzy matching or string comparison. This makes the method the most reliable lookup option.
  • Testing Events: Pre-season testing rows have RoundNumber 0, and get_event_by_round(year, 0) raises ValueError. Use get_event_by_name(year, "Pre-Season Test") (or the testing EventName of that year) for testing events.
Example Usage:
Advanced Example - Analyzing Round Progression:
Practical Example - Loading Specific Round Data:
To iterate through a season chronologically, use get_event_by_round() with a range over the race rounds. Take the round count from get_event_schedule(year, include_testing=False).

get_event_by_name

Retrieves an Event object by its name with optional fuzzy matching. This function provides flexible event lookup using event names, partial names, circuit names, or common abbreviations. It is ideal for interactive use, user-facing applications, or unknown event name formats. An exact (case-insensitive) name match comes first, then the alias table for circuit, city, and country names, then fuzzy matching. It handles typos, case variations, and partial matches. For example, “Silverstone”, “British”, “british grand prix”, and “BRITISH GP” all match the British Grand Prix. Parameters:
int
required
The Formula 1 season year (2018-2026). A year without schedule data raises ValueError (EventNotInSeasonError for an alias).
str
required
The event name or partial name to search for. The function accepts multiple formats:Full official names:
  • "Belgian Grand Prix"
  • "British Grand Prix"
  • "Monaco Grand Prix"
Partial names:
  • "Belgian" → matches “Belgian Grand Prix”
  • "British" → matches “British Grand Prix”
  • "Monaco" → matches “Monaco Grand Prix”
Circuit names:
  • "Spa" → matches “Belgian Grand Prix” (Spa-Francorchamps)
  • "Silverstone" → matches “British Grand Prix”
  • "Monza" → matches “Italian Grand Prix”
Case-insensitive:
  • "belgian grand prix", "BELGIAN GP", "Belgian" all work
Testing events:
  • A testing event matches only by its full name, for example "Pre-Season Testing" in 2025. Aliases and fuzzy matching never return a testing event.
  • When two testing events of a season have the same name, tif1 adds a number in date order. In 2026, the names are "Pre-Season Testing 1" and "Pre-Season Testing 2". The shared name "Pre-Season Testing" matches the first test, as in fastf1.
  • To get a test by its number, use get_testing_event(year, test_number).
bool
default:"False"
Controls the string matching behavior:
  • False (default): Uses fuzzy matching algorithm to find the best match. Tolerates typos, partial names, case variations, and common abbreviations.
  • True: Requires the full EventName. The comparison ignores case. Aliases and fuzzy matching are not applied.
When to use exact_match=True:
  • Validating user input against known event names
  • Ensuring no false positives in automated systems
  • When the exact official event name is available
When to use exact_match=False (default):
  • Interactive applications where users type event names
  • When accepting partial or abbreviated input
  • When flexible input handling is needed
Returns:
Event
An Event object (pandas Series subclass) containing all event metadata and methods for session access.
Raises:
  • EventNotFoundError: If no event matches the name. With exact_match=False, the error is the subclass FuzzyMatchError and the message is No event matching '<name>' in <year>. With exact_match=True, the message is No exact match found for event '<name>' in <year>. This class is a ValueError subclass, exported as tif1.EventNotFoundError, so except ValueError also catches it.
  • EventNotInSeasonError: If an alias names an event that is not on the calendar of that year, for example 'Suzuka' refers to the Japanese Grand Prix, which is not on the 2021 calendar. This class is a subclass of EventNotFoundError, exported as tif1.EventNotInSeasonError.
  • ValueError: If the season has no events (No events found for <year>).
  • InvalidDataError: If the schedule data is malformed or cannot be parsed
Behavior & Implementation Details:
  • Fuzzy Matching Algorithm: A query found inside the location, country, or name of exactly one event wins. Otherwise the rapidfuzz ratio picks the closest event.
  • Score Floor: A fuzzy match needs a score of at least 70 (rapidfuzz ratio, 0-100). Below that, the function raises EventNotFoundError instead of returning the closest event. A typo still resolves, and tif1 logs a warning such as Correcting user input 'Monacco' to 'Monaco Grand Prix'. In 2025, “Zandvort”, “Sao Paolo”, and “Bahrein” resolve. “xyz”, “Paris”, and “Grand Prix” raise.
  • Performance: The lookup takes well under a millisecond. It does not build the season schedule. An exact name or an alias skips the fuzzy step. The first fuzzy lookup in a process also imports rapidfuzz, which adds a few milliseconds. The fuzzy step scores all events in the season (typically 20-24 events).
  • Caching: The schedule is cached. Each call runs the matching again and builds a new Event object.
Example Usage:
Advanced Example - User Input Handling:
For user-facing applications, fuzzy matching accepts partial names and typos. Always show the matched EventName, because a typo can resolve to an unexpected event. For programmatic access, use get_event_by_round() or exact_match=True.

get_event_schedule

Retrieves the complete event schedule for a Formula 1 season as an EventSchedule DataFrame. This function shows the complete season calendar. It includes all Grand Prix events, their sessions, timing information, and metadata. It is the foundation for season-wide analysis and iteration. The returned EventSchedule object is a specialized pandas DataFrame subclass. It includes all the standard DataFrame functionality plus F1-specific methods for event lookup and filtering. Each row represents a single Grand Prix event with full metadata. Parameters:
int
required
The Formula 1 season year (2018-2026). A year without schedule data returns an empty EventSchedule.
bool
default:"True"
Controls whether pre-season testing events are included in the returned schedule.
  • True (default): Includes all events including pre-season testing sessions
  • False: Excludes testing events, returning only championship Grand Prix events
Use cases for include_testing=False:
  • Championship analysis (only counting points-scoring events)
  • Season statistics (excluding non-competitive sessions)
  • Calendar visualization (showing only race weekends)
Use cases for include_testing=True:
  • Complete data availability overview
  • Pre-season analysis and testing data
  • Complete event iteration
Returns:
EventSchedule
An EventSchedule object (pandas DataFrame subclass) containing all events for the specified year. The DataFrame includes the following columns:Core Event Information:
  • EventName: Official short name (for example, “Belgian Grand Prix”)
  • Location: Circuit or venue name (for example, “Spa-Francorchamps”)
  • OfficialEventName: Full official event title with sponsors (for example, “FORMULA 1 ROLEX BELGIAN GRAND PRIX 2021”)
  • RoundNumber: Championship round number (1-indexed integer; 0 for testing rows)
  • Country: Country where the event takes place (for example, “Belgium”)
  • EventDate: Main event date as pandas Timestamp (typically race day)
  • EventFormat: Format type - “conventional”, “sprint” (2021-2022), “sprint_shootout” (2023), “sprint_qualifying” (2024 onward), or “testing”
Session Information:
  • Session1, Session2, Session3, Session4, Session5: Names of available sessions (for example, “Practice 1”, “Qualifying”, “Race”)
  • Session1Date, Session2Date, …: Local session start times with a fixed UTC offset
  • Session1DateUtc, Session2DateUtc, …: Naive pandas Timestamps in UTC (the local time minus GmtOffset)
  • F1ApiSupport, GmtOffset: API support flag and the UTC offset of the circuit
The EventSchedule object also provides specialized methods:
  • get_event_by_round(round_number): Get a specific event by round number
  • get_event_by_name(name, strict_search=False): Get a specific event by name with optional fuzzy matching
  • get_event(identifier, strict_search=False): Get an event by either round number or name
All standard pandas DataFrame operations are available (filtering, sorting, grouping, etc.).
Raises:
  • InvalidDataError: If the schedule data is malformed or cannot be parsed
A year without schedule data returns an empty EventSchedule. A failed fetch logs a warning and falls back to the cached or vendored schedule. Behavior & Implementation Details:
  • Data Source: The current and future seasons come from the live theOehrly/f1schedule repository (raw.githubusercontent.com, the same file FastF1 reads). tif1 fetches the file again once the cached copy is older than schedule_ttl_hours (default 6). Past seasons come from the vendored JSON files (2018 onwards); earlier years fall back to the repository. The data source is invisible to the caller.
  • Caching: The raw schedule data is cached in memory after the first request. Each call builds a new EventSchedule from it, which takes a few milliseconds.
  • Testing Events: Testing events have EventFormat="testing" and RoundNumber 0. They come after the race weekends in the frame, although they take place before the season.
  • Session Columns: The number of session columns varies by event format. Conventional weekends typically have 5 sessions (FP1, FP2, FP3, Q, R), while sprint weekends may have different configurations. Unused session columns contain NaN.
  • Timezone Handling: Local times carry the UTC offset of the circuit (GmtOffset, “+02:00” for Spa in August). The SessionNDateUtc columns hold the same start times in UTC as naive timestamps. An event without a usable GmtOffset has NaT in those columns.
  • Performance: A call takes a few milliseconds for vendored or cached data. A year that comes from the live repository adds the network time to the first call.
Example Usage:
Advanced Example - Season Analysis:
Practical Example - Export to CSV:
Practical Example - Calendar Visualization:
Use get_event_schedule() to work with the complete season as a DataFrame for analysis, filtering, or iteration. For a single event by name, use get_event_by_name(), which does not build the schedule.
The get_events(year) function is an alias for get_event_schedule(year, include_testing=True). Both return the same EventSchedule object. Use whichever name fits the use case.

Event

The Event class is a pandas Series subclass representing a single Grand Prix event with metadata and session access.

Properties

int
The season year (read-only property).

Series Data Fields

Access event data using dictionary-style indexing:
str
The official event name (for example, “Belgian Grand Prix”).
str
The event location (for example, “Spa-Francorchamps”).
str
The full official event name (for example, “FORMULA 1 ROLEX BELGIAN GRAND PRIX 2021”).
int
The championship round number.
str
The country where the event takes place.
pd.Timestamp
The main event date.
str
The event format: “conventional”, “sprint”, “sprint_shootout”, “sprint_qualifying”, or “testing”.
str
Session names (for example, “Practice 1”, “Qualifying”, “Race”).
datetime
Local session date and time with a fixed UTC offset.
pd.Timestamp
Naive session timestamps in UTC: the local time minus GmtOffset. NaT when the event has no usable GmtOffset.
Example:

Methods

get_session(identifier)

Get a Session object for a specific session within this event. Parameters:
  • identifier: Session identifier (the fastf1 argument name; positional use is unchanged) - can be:
    • Session name (for example, “Qualifying”, “Race”)
    • Session abbreviation (for example, “Q”, “R”, “FP1”)
    • Session number (1-5, the position in the session list of the event)
  • session_name: The earlier tif1 keyword for identifier. Give one of the two
Returns:
  • Session object ready to load data
Raises:
  • ValueError: If the session identifier is invalid or does not exist for this event, or if both identifier and session_name (or neither) are given
Example:

get_session_name(identifier)

Return the canonical session name for a session identifier. Parameters:
  • identifier: Session number (1-5), abbreviation (FP1-FP3, Q, SQ, SS, S, R), or full session name (case-insensitive). Partial names such as “Prac” are not matched
Returns:
  • Canonical session name
Raises:
  • ValueError: If the identifier is invalid or the session does not exist for this event
Example:

get_session_date(identifier, utc=False)

Return the date and time of a specific session. Parameters:
  • identifier: Session name, abbreviation, or number
  • utc: If True, return the naive UTC timestamp from SessionNDateUtc. If False, return local time with the UTC offset
Returns:
  • Timestamp for the session
Raises:
  • ValueError: If session does not exist or local timestamp unavailable
Example:

get_race()

Return the race session (convenience method).

get_qualifying()

Return the qualifying session (convenience method).

get_sprint()

Return the sprint session (convenience method).

get_sprint_shootout()

Return the sprint shootout session (convenience method).

get_sprint_qualifying()

Return the sprint qualifying session (convenience method).

get_practice(number)

Return the specified practice session. Parameters:
  • number: Practice session number (1, 2, or 3)
Example:

EventSchedule

The EventSchedule class is a pandas DataFrame subclass containing all events for a season.

Properties

int | None
The season year.
pandas.DataFrame
The schedule as a plain pandas.DataFrame (fastf1 parity). Some debuggers and IDEs show a plain frame better than a subclass.

Methods

get_event_by_round(round_number)

Return an Event for a specific championship round. Parameters:
  • round_number: The round number (1-indexed)
  • round: The fastf1 keyword for the same value (deprecated in fastf1 3.9.0). Give one of the two
Returns:
  • Event object
Raises:
  • ValueError: If the round number is invalid, if it is 0 (testing events have no round), or if both keywords (or neither) are given

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

Return an Event by name with optional fuzzy matching. Parameters:
  • name: Event name, location, or country
  • strict_search: If True, requires an exact (case-insensitive) event name match
  • exact_match: The fastf1 name of strict_search. Either keyword turns on the exact match
Returns:
  • Event object or None if not found. A name with a fuzzy score below 70 also gives None; this method does not raise EventNotFoundError.

get_event(identifier, strict_search=False, *, exact_match=False)

Return an Event by round number or name. Parameters:
  • identifier: Round number (int) or event name (str)
  • strict_search: If True, requires exact name match
  • exact_match: The fastf1 name of strict_search
Returns:
  • Event object or None if not found
Example:

Session name formats

While tif1 is flexible with session names, use these standard formats for consistency:
Session names are case-insensitive, and the abbreviations FP1-FP3, Q, S, SS, SQ, and R resolve to the standard names. Session names do not use fuzzy matching, so “P1” raises ValueError.

Complete Examples

List all events and sessions

Work with event objects

Fuzzy event matching

Iterate through season

Multi-year comparison

Find events by criteria

Load all sessions for an event

Build a season calendar

Analyze sprint weekend evolution

Export season data to multiple formats

Build an event lookup CLI tool

Track calendar changes across years


Best Practices

Performance Optimization

1. Use get_event_by_name() for a single lookup get_event() and get_event_by_round() build the full season schedule on each call. get_event_by_name() reads the cached raw schedule directly:
2. Cache schedule data for repeated queries For multiple queries in the same year, fetch the schedule once:
3. Use include_testing=False when appropriate Exclude testing events when they are not needed. This reduces data size:
4. Use pandas operations for filtering Use pandas DataFrame operations for efficient filtering:

Error Handling

1. Always handle DataNotFoundError Event and session data may not always be available:
2. Validate round numbers Check round number validity before lookup:
3. Handle fuzzy matching ambiguity A typo resolves to the closest event, which can be a different race. A generic name such as “Grand Prix” matches no event and raises EventNotFoundError. Verify the result:

Code Organization

1. Create helper functions for common patterns
2. Use type hints for clarity
3. Document expected data availability

Data Validation

1. Verify session availability before loading
2. Validate event format expectations
3. Check data completeness

Testing and Development

1. Use known events for testing
2. Mock network calls in tests
3. Test fuzzy matching edge cases

Common Patterns

Pattern: Season-wide analysis

Pattern: Event discovery workflow

Pattern: Batch processing


Troubleshooting

Issue: Fuzzy matching returns the wrong event

Problem: get_event_by_name() returns an unexpected event. tif1 logs Correcting user input '...' to '...'. Solution: The event name might be ambiguous, or a typo close to another event. Fuzzy matching picks the closest event when its score is at least 70. Try:

Issue: Session not available

Problem: get_session() raises ValueError for a session that should exist. Solution: Check actual session availability:

Issue: Empty schedule

Problem: get_events() returns an empty schedule. Solution: Seasons from 1950 to 2017 come from the packaged Ergast race tables; seasons from 2018 ship with tif1 as vendored f1schedule files. Other years come from the live theOehrly/f1schedule repository. The schedule is empty when the repository has no file for the year (HTTP 404). It is also empty when the fetch fails and no cached or vendored copy exists. No exception is raised:

Issue: Incorrect round numbers

Problem: Round numbers do not match expectations. Solution: Round numbers can change between years:

Issue: Missing session timing data

Problem: get_session_date() raises ValueError. Solution: Not all events have complete timing data:

Core API

Load and work with session data (Session, Laps, Telemetry).

Schedule Validation

Schedule data validation and schema.

HTTP & Networking

CDN fetching, caching, and network configuration.

Data Flow

Understand how event data flows through tif1.

Caching Strategy

Learn about tif1’s caching mechanisms.

CLI Usage

Use tif1’s command-line interface for event discovery.

API Reference Summary

Functions

Classes

Key Properties

Event properties:
  • year: Season year (int)
  • EventName: Official event name (str)
  • Location: Circuit name (str)
  • Country: Country (str)
  • RoundNumber: Championship round (int)
  • EventDate: Event date (Timestamp)
  • EventFormat: “conventional”, “sprint”, “sprint_shootout”, “sprint_qualifying”, or “testing” (str)
EventSchedule properties:
  • year: Season year (int | None)
  • All pandas DataFrame properties and methods

Need help? For issues with the events API, check the Troubleshooting section above. To report a problem, open an issue on GitHub with details about the use case.
Last modified on November 3, 2026