Skip to main content
tif1.ergast is a drop-in replacement for fastf1.ergast. from tif1.ergast import Ergast keeps the same thirteen methods, the same keyword arguments, the same flattened column names and the same response classes. The data comes from the TracingInsights Stats repository first, which holds the complete Jolpica response of every table and round as one file. The Jolpica API answers only what that repository cannot.

Overview

The Ergast database (continued by Jolpica) is the reference for Formula 1 results since 1950. It holds race, qualifying and sprint classifications, lap timings (1996 onward) and pit stops (2011 onward). It also holds championship standings, race schedules, drivers, constructors, circuits and finishing statuses. tif1 reads that data in two ways:
  • Directly, through tif1.ergast.Ergast, for analysis across seasons, rounds or drivers.
  • Inside Session, where the official classification fills session.results, orders session.drivers, and backs session.pit_stops, session.driver_standings and session.constructor_standings. Sessions before 2018 are built from Ergast data alone. Refer to Core API for the session view.

Data sources

A query that Stats can answer never touches Jolpica. A Stats file that is missing on every mirror or empty (total of 0) falls through to Jolpica for that round only. The answer is cached either way.
The Stats files are snapshots of the Jolpica answers taken when each round was published. Results, times, positions, points and lap data do not change afterwards, but Jolpica keeps editing metadata. That covers Wikipedia URLs (http to https), localities and circuit names, a driver’s current permanent number, and the finishing-status vocabulary (Lapped and Retired since 2025). Those edits reach tif1 when the repository regenerates a round. Pin source="jolpica" for a query that needs the live metadata.
Jolpica lists drivers who only drove practice sessions, which no Stats file contains. get_driver_info therefore always uses Jolpica, and get_finishing_status does too because the Stats files carry no numeric statusId.

Freshness

Results get corrected after a weekend (penalties, appeals) and standings move on, so the current season is never held longer than the TTL. tif1 cache-clear --ergast drops only this tier.

Ergast

"pandas" | "raw" | "polars"
default:"pandas"
"pandas" returns ErgastSimpleResponse or ErgastMultiResponse depending on the endpoint. "raw" returns ErgastRawResponse, the JSON-like data as a list. "polars" returns polars frames: an ErgastPolarsResponse (a polars.DataFrame with the same source, total_results, is_complete and paging methods) for simple endpoints, otherwise an ErgastMultiResponse whose description and content are polars frames.
bool
default:"True"
Cast values from their string form to numbers, dates, times and timedeltas.
int | None
default:"None"
Maximum number of result rows. None returns every row when the Stats repository answered and the API default of 30 when Jolpica did. Set it to page through a result set with get_next_result_page().
"auto" | "stats" | "jolpica"
default:"auto"
Pin the data source. "stats" raises DataNotFoundError for queries the repository cannot answer; "jolpica" skips the repository. Every response reports the source that answered through .source.

Methods

Every method accepts result_type, auto_cast, limit and offset to override the instance defaults for one call. The selectors are fastf1’s: season (a year or "current"), round (a number or "last"), and circuit, constructor and driver (Ergast ids such as "monza", "mclaren", "norris"). The row filters are grid_position, results_position, fastest_rank, status (a numeric status id), lap_number, stop_number and standings_position. Season-wide queries (get_race_results(season=2024)) are assembled from the per-round files in one parallel fetch. Filters on a results-like endpoint (driver, constructor, circuit, grid_position, results_position, fastest_rank) are applied locally. A status filter, a query without a season, or a qualifying query with grid_position/fastest_rank goes to Jolpica, which holds the tables those need. Standings without a round return the standings after the last completed round, the final standings for a past season.

Example


Response classes

ErgastSimpleResponse

A pandas DataFrame (an ErgastResultFrame) with the response metadata of ErgastResponseMixin. Slicing it returns an ErgastResultFrame without the metadata, as in fastf1.

ErgastPolarsResponse

The polars twin of ErgastSimpleResponse: a polars.DataFrame with the response metadata of ErgastResponseMixin, returned by the simple endpoints with result_type="polars". Frames derived from it (head, filter, slices) are plain polars frames without the metadata. The class is built on first use, so importing tif1.ergast never imports polars.

ErgastMultiResponse

Holds the descriptive rows in description (one per race or standings list) and the main data in content, a list with one frame per description row. Both are pandas frames, or polars frames with result_type="polars".

ErgastRawResponse

A list of the JSON-like response elements, cast when auto_cast is on. The list is a private copy, so mutating it never changes the cache.

ErgastResponseMixin

int
Total number of rows available for the request.
bool
True when the response holds every available row (offset of zero and limit at least total).
str
"stats" or "jolpica": the source that answered. A tif1 addition.
response
The next page within the request’s limit. Raises ValueError after the last page.
response
The previous page. Raises ValueError before the first page.

Columns

The flattened column names are fastf1’s (tif1.ergast.structure carries the same tables). Two things differ, both additive:
  • totalRaceTime is the true total race time of every classified driver, built from Time.millis. fastf1 parses Time.time instead, which Ergast fills with the gap to the winner for everyone but the winner. The gap is available as totalRaceTimeGap (zero for the winner). totalRaceTimeMillis is unchanged.
  • Race schedules also flatten Jolpica’s SprintQualifying and SprintShootout session keys into sprintQualifyingDate/sprintQualifyingTime and sprintShootoutDate/sprintShootoutTime.
Rows without a value for a column hold NaN (or NaT for times), which is what pandas fills in when fastf1 builds its frames.

Legacy helpers

fetch_season(year), fetch_day(year, gp, day) and fetch_results(year, gp, session) keep fastf1’s signatures and return the raw Races lists, routed like every other query.

Configuration

Errors

  • ErgastInvalidRequestError: Jolpica rejected the request (a 404 or another non-200 answer), or Jolpica is needed but ergast_fallback is off.
  • ErgastJsonError: a Jolpica answer could not be parsed.
  • RateLimitExceededError: Jolpica kept answering 429 after three retries. A NetworkError subclass.
  • DataNotFoundError: source="stats" was pinned and the repository cannot answer.
All three Ergast errors derive from ErgastError, a TIF1Error. Refer to Exceptions.
Last modified on October 30, 2026