import type { RaceTrackerDriver, RaceTrackerProps, SectorState, TrackStatus, Tyre, } from "@/components/race-tracker"; import { circuits } from "@/lib/circuits"; import { locate, type Circuit } from "@/lib/track"; export const OPENF1_URL = "https://api.openf1.org/v1"; // The OpenF1 rows the tracker reads, trimmed to the fields it uses. export type OpenF1Session = { session_key: number; meeting_key: number; circuit_key: number; circuit_short_name: string; session_name: string; date_start: string; date_end: string; }; export type OpenF1Meeting = { meeting_key: number; meeting_name: string }; export type OpenF1Driver = { driver_number: number; name_acronym: string; team_colour: string | null; }; export type OpenF1Location = { date: string; driver_number: number; x: number; y: number; }; export type OpenF1Interval = { date: string; driver_number: number; /** Seconds, `"+1 LAP"` once lapped, null for the leader. */ gap_to_leader: number | string | null; }; export type OpenF1Position = { date: string; driver_number: number; position: number; }; export type OpenF1Lap = { driver_number: number; lap_number: number; date_start: string | null; lap_duration: number | null; duration_sector_1: number | null; duration_sector_2: number | null; duration_sector_3: number | null; }; export type OpenF1Stint = { driver_number: number; stint_number: number; lap_start: number; lap_end: number | null; compound: string | null; }; export type OpenF1RaceControl = { date: string; category: string; flag: string | null; scope: string | null; sector: number | null; message: string; }; export type OpenF1Query = Record; /** * GETs one endpoint. Keys may carry OpenF1's comparison operators, so * `{ "date>": iso }` becomes `date>2026-...`. A token is only needed for live * sessions; historical data is free. */ export async function openf1( endpoint: string, query: OpenF1Query, { token, signal }: { token?: string; signal?: AbortSignal } = {}, ): Promise { const params = Object.entries(query) .filter(([, value]) => value !== undefined) .map(([key, value]) => { const [, name, op = "="] = key.match(/^(.*?)(<=|>=|<|>)?$/)!; return `${name}${op}${encodeURIComponent(String(value))}`; }) .join("&"); let response: Response; try { response = await fetch(`${OPENF1_URL}/${endpoint}?${params}`, { headers: token ? { Authorization: `Bearer ${token}` } : undefined, signal, }); } catch (reason) { if (signal?.aborted) throw reason; // While any session is live OpenF1 turns away every request without a // token, past sessions too, and without CORS headers, so a browser sees // only a failed fetch. throw new Error( "Couldn't reach OpenF1. It closes to requests without a token while a session is live.", ); } // OpenF1 answers an empty match with a 404. if (response.status === 404) return []; if (response.status === 401) { throw new Error( "OpenF1 wants a token: a session is live, or this one needs it.", ); } if (response.status === 429) { throw new Error("OpenF1 rate limit reached. Trying again shortly."); } if (!response.ok) { throw new Error( `OpenF1 ${endpoint}: ${response.status} ${response.statusText}`, ); } return response.json(); } /** Everything the tracker needs from one session, as it accumulates. */ export type OpenF1Feed = { session: OpenF1Session; meeting?: OpenF1Meeting; drivers: OpenF1Driver[]; locations: OpenF1Location[]; intervals: OpenF1Interval[]; positions: OpenF1Position[]; laps: OpenF1Lap[]; stints: OpenF1Stint[]; raceControl: OpenF1RaceControl[]; }; export type OpenF1Race = Pick< RaceTrackerProps, | "circuit" | "title" | "subtitle" | "lap" | "laps" | "drivers" | "fastestLap" | "status" >; const time = (date: string) => Date.parse(date); /** The newest row per driver at or before `at`. */ function latest( rows: T[], at: number, ) { const found = new Map(); for (const row of rows) { if (time(row.date) > at) continue; const held = found.get(row.driver_number); if (!held || held.date < row.date) found.set(row.driver_number, row); } return found; } const TYRES: Record = { SOFT: "soft", MEDIUM: "medium", HARD: "hard", INTERMEDIATE: "intermediate", WET: "wet", }; /** Track-wide state from race control, with any sector yellow on top of green. */ function trackStatus( rows: OpenF1RaceControl[], at: number, ): TrackStatus | undefined { let status: TrackStatus | undefined; const yellows = new Set(); for (const row of rows) { if (time(row.date) > at) continue; const message = row.message.toUpperCase(); if (row.category === "SafetyCar" && message.includes("DEPLOYED")) { status = message.includes("VIRTUAL") || message.includes("VSC") ? "vsc" : "sc"; } else if (row.category === "Flag" && row.scope === "Track") { if (row.flag === "RED") status = "red"; else if (row.flag === "CHEQUERED") status = "chequered"; else if (row.flag === "GREEN" || row.flag === "CLEAR") status = "green"; } else if ( row.category === "Flag" && row.scope === "Sector" && row.sector ) { if (row.flag?.includes("YELLOW")) yellows.add(row.sector); else if (row.flag === "CLEAR" || row.flag === "GREEN") yellows.delete(row.sector); } } return status === "green" && yellows.size ? "yellow" : status; } /** * The race as it stood at `at` (epoch ms), ready to spread into * ``. Pass the previous result back as `previous` so each car * is matched to the stretch of track it was last seen on. */ export function raceAt( feed: OpenF1Feed, at: number, { circuit = circuits[feed.session.circuit_key], laps, previous, }: { circuit?: Circuit; laps?: number; previous?: OpenF1Race | null } = {}, ): OpenF1Race | null { if (!circuit) { throw new Error( `No outline for circuit_key ${feed.session.circuit_key}. Pass one as \`circuit\`.`, ); } const positions = latest(feed.positions, at); if (!positions.size) return null; const locations = latest(feed.locations, at); const intervals = latest(feed.intervals, at); const before = new Map(previous?.drivers.map((d) => [d.number, d.progress])); // Laps under way by `at`, and the sector and lap times finished by then. type Run = { lap: OpenF1Lap; start: number; splits: (number | null)[] }; const runs = new Map(); const sessionBest = [Infinity, Infinity, Infinity]; const personalBest = new Map(); let fastestLap: OpenF1Race["fastestLap"]; const code = new Map( feed.drivers.map((d) => [d.driver_number, d.name_acronym]), ); for (const lap of feed.laps) { if (!lap.date_start || time(lap.date_start) > at) continue; const start = time(lap.date_start); const splits = [ lap.duration_sector_1, lap.duration_sector_2, lap.duration_sector_3, ]; // A sector counts once it has a time and the clock has passed its end. let end: number | null = start; const done = splits.map((split) => { if (split === null || end === null) { end = null; return null; } end += split * 1000; return end <= at ? split : null; }); const mine = personalBest.get(lap.driver_number) ?? [ Infinity, Infinity, Infinity, ]; done.forEach((split, i) => { if (split === null) return; mine[i] = Math.min(mine[i], split); sessionBest[i] = Math.min(sessionBest[i], split); }); personalBest.set(lap.driver_number, mine); if (lap.lap_duration && start + lap.lap_duration * 1000 <= at) { if (!fastestLap || lap.lap_duration < fastestLap.time) { fastestLap = { code: code.get(lap.driver_number) ?? "", time: lap.lap_duration, }; } } const list = runs.get(lap.driver_number) ?? []; list.push({ lap, start, splits: done }); runs.set(lap.driver_number, list); } // A car with no gap for a minute, while others have them, has stopped. Only // judged once the rows held go back that far, or every car looks stopped. const oldest = feed.intervals.reduce( (min, row) => Math.min(min, time(row.date)), at, ); const judged = at - oldest >= 60_000 && [...intervals.values()].some((row) => at - time(row.date) < 60_000); const drivers = feed.drivers.flatMap((driver): RaceTrackerDriver[] => { const number = driver.driver_number; const position = positions.get(number)?.position; if (position === undefined) return []; const location = locations.get(number); const where = location ? locate(circuit, location.x, location.y, before.get(number)) : undefined; const interval = intervals.get(number); const gap = interval?.gap_to_leader; const mine = (runs.get(number) ?? []).sort((a, b) => a.start - b.start); const current = mine.at(-1); const last = mine.findLast( (run) => run.lap.lap_duration && run.start + run.lap.lap_duration * 1000 <= at, ); const bests = personalBest.get(number); const stint = feed.stints.findLast( (s) => s.driver_number === number && current && s.lap_start <= current.lap.lap_number && (s.lap_end ?? Infinity) >= current.lap.lap_number, ); const out = judged && position > 1 && (!interval || at - time(interval.date) >= 60_000); return [ { number, code: driver.name_acronym, color: driver.team_colour ? `#${driver.team_colour}` : undefined, position, progress: where?.progress ?? before.get(number) ?? 0, gap: typeof gap === "number" && position > 1 ? gap : undefined, lapsDown: typeof gap === "string" ? Number.parseInt(gap.replace(/\D+/g, ""), 10) || 1 : undefined, lastLap: last?.lap.lap_duration ?? undefined, sectors: current?.splits.map((split, i): SectorState | null => split === null ? null : split <= sessionBest[i] ? "fastest" : bests && split <= bests[i] ? "personal" : "done", ), tyre: stint?.compound ? TYRES[stint.compound] : undefined, // The pit lane runs beside the track, well off the racing line. status: out ? "out" : where && where.offset > 250 ? "pit" : undefined, }, ]; }); const leader = drivers.find((d) => d.position === 1); const leaderLap = runs.get(leader?.number ?? -1)?.at(-1)?.lap.lap_number ?? 0; return { circuit, title: feed.meeting?.meeting_name ?? feed.session.circuit_short_name, subtitle: `${feed.session.circuit_short_name} · ${feed.session.session_name}`, lap: laps ? Math.min(laps, leaderLap) : leaderLap, laps, drivers, fastestLap, status: trackStatus(feed.raceControl, at), }; }

Code