Skip to main content

Formula 1 — additional Python functions

Hand-written wrappers, loaders, and helpers in sportsdataverse.f1 that are not generated API-endpoint wrappers (those have their own reference pages).

Jolpica F1 API (Ergast-compatible)​

f1_laps​

f1_laps(season: 'str', round: 'str', *, return_as_pandas: 'bool' = False, **kwargs: 'Any') -> 'Union[pl.DataFrame, pd.DataFrame]'

Lap times of one race: one row per driver per lap (1996+), all pages.

Endpoint: GET https://api.jolpi.ca/ergast/f1/{season}/{round}/laps.json, requested with limit=100 and offset advanced page by page until MRData.total timings have been read.

Parameters

ParameterTypeDefaultDescription
seasonstrFour-digit season year, or current.
roundstrRound number within the season, or last / next.
return_as_pandasboolFalsereturn a pandas DataFrame instead of polars.

Returns

A polars/pandas DataFrame with the laps_page columns (season, round, race_*, lap_number, driver_id, position, time), concatenated across pages; zero rows (same columns) when the race has no lap data (before 1996, or a round not yet run).

col_nametypedescription
roundInt64
seasonInt64
race_circuit_location_countryString
race_circuit_location_latFloat64
race_circuit_location_localityString
race_circuit_location_longFloat64
race_circuit_idString
race_circuit_nameString
race_circuit_urlString
race_dateString
race_nameString
race_timeString
race_urlString
lap_numberInt64
driver_idString
positionInt64
timeString

Raises

ExceptionDescription
sportsdataverse.errors.NoDataErrorThe Jolpica API returned 404 (unknown season or round).
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, or an empty or unreadable 200 body), or a page came back empty before MRData.total timings were read -- the answer is unknown, not empty.

Example

from sportsdataverse.f1 import f1_laps

df = f1_laps(2024, 1)
print(df.shape) # (1129, 17) -- 12 requests

# Pipeline next step (one line)

import polars as pl

df.filter(pl.col("driver_id") == "max_verstappen").select("lap_number", "position", "time")