tif1.mvapi is the tif1 version of fastf1.mvapi. It reads circuit layouts from the MultiViewer API, the source that fastf1 uses for get_circuit_info(). The API needs no account.Overview
The MultiViewer API holds one layout per circuit and season. A layout has the corners, the marshal lights and sectors, the track map rotation, the track outline, and the pit lane time loss. tif1 uses it in two ways:- Directly, through the
tif1.mvapifunctions on this page. - Inside
Session, as the backup source ofsession.get_circuit_info()when thecorners.jsonfile of the session cannot supply the marshal data.
User-Agent: tif1/{version} (+https://github.com/TracingInsights/tif1) header. They also work in Pyodide. A failed request never raises: the functions return None. get_circuit and get_circuits_index log the failure at INFO level. get_circuit_info also logs a warning when it gets no layout.
MultiViewer knows 32 circuits and has no layout before 2018. For a year before the first layout of a circuit, it answers with its earliest layout: a 2016 Sakhir request gives the 2019 layout.
How session.get_circuit_info() uses it
session.get_circuit_info() builds the CircuitInfo in these steps:
- It fetches the
corners.jsonfile of the session. The new schema holds the corners with their letters, the marshal lights and sectors, and the pit lane time loss. It also holds the track outline, the track sections, the mini-sector index, and the circuit keys. Such a file needs no MultiViewer request. - It asks MultiViewer once when the file is missing, is invalid, or uses the old schema (the 2021 to 2024 seasons, corners and rotation only). A new-schema file without corners or marshal lights also causes a request. Seasons before 2018 have no file, so their layout is the earliest MultiViewer layout of the circuit. A circuit that MultiViewer does not know, such as Aida (1995 Pacific Grand Prix), gets empty frames.
- It finds the circuit key in this order: the
CircuitKeyof a new-schema file, the packaged circuit table, and the live circuit index. The live index is matched by circuit name and country. - It merges the two sources. Corners and rotation from
corners.jsonalways win. MultiViewer fills the marshal frames, the corner letters, and the empty extras.CircuitInfo.sourcenames the sources, for example"corners.json+multiviewer", or is""when neither source answered. - It fits the missing marker distances on the fastest lap of the session, on pandas and polars sessions. The distances from
corners.jsonare kept. Seasons before 2018 have no telemetry, so their markers keep a missingDistance.
session.get_circuit_info() sends 146 for Mugello, as fastf1 does. The functions on this page send the key as given.
In offline_mode, session.get_circuit_info() does not ask MultiViewer. A failed MultiViewer request leaves the marshal frames empty, and get_circuit_info() still returns the corners from the file. Refer to get_circuit_info() and CircuitInfo.
Caching
The answers are kept in thejson tier of the SQLite cache (cache.sqlite).
The layout also stays in memory on the session after the first
get_circuit_info() call. In offline_mode, the functions read the cache only.
The packaged circuit table
tif1 ships data/circuits/mv_circuits.json, a table keyed by the Ergast CircuitId of each event. Each entry holds the MultiViewer circuit key, the country key, the IOC country code, the circuit name, and the country. The schedule already carries the CircuitId, so the circuit key needs no request. session.session_info reads the same table for its Meeting.Circuit.Key and Meeting.Country values. tools/vendor_mv_circuits.py generates the table from the circuit index.
get_circuit_info
tif1.get_circuit_info is the same function. It is not the session.get_circuit_info() method.
Parameters:
The championship year. MultiViewer answers with its most recent layout at or before that year. For a year before its first layout of the circuit, it answers with its earliest layout (2016 gives the 2019 layout of Sakhir).
The circuit key of the F1 live-timing data (the MultiViewer
circuitKey), for example 63 for Sakhir or 22 for Monaco.corners,marshal_lights,marshal_sectors: frames with the columnsX,Y,Number,Letter,Angle,Distance.Distanceis empty untiladd_marker_distance()fits itrotation: the track map rotation in degrees- The extras from the same answer:
circuit_key,circuit_name,location,country,country_code,country_key,pit_loss,track, andmini_sector_index source:"multiviewer"
None when the API did not answer. tif1 then logs a warning.get_circuit
/api/v1/circuits/{circuit_key}/{year}). The first answer is kept in the SQLite cache without expiry.
Returns:
- The JSON object (
circuitKey,circuitName,corners,marshalLights,marshalSectors,rotation,pitLoss,x,y, and others) Nonewhen the request failed, when the circuit is unknown, or when the cache has no answer inoffline_mode
get_circuits_index
/api/v1/circuits): every circuit that MultiViewer knows, keyed by the circuit key as a string. Each entry holds name, country, years, circuitKey, countryKey, iocCountryCode, and pitLoss. The index stays in the cache for schedule_ttl_hours.
Returns:
- The index, or
Nonewhen neither the network nor the cache has it
CircuitInfo
tif1.mvapi.CircuitInfo is the same class as tif1.models.CircuitInfo. Refer to CircuitInfo for its attributes and add_marker_distance().
Related pages
- Core API:
session.get_circuit_info()andsession.session_info - Models: the
CircuitInfoclass - Cache: the SQLite
jsontier - Migration from fastf1: what still differs from fastf1