Fastf1

FastF1 — Formula 1 Data

Before writing queries, consult references/api-reference.md for endpoints, ID conventions, and data shapes.

Quick Start

Prefer the CLI — it avoids Python import path issues:

sports-skills f1 get_race_schedule --year=2025
sports-skills f1 get_race_results --year=2025 --event=Monza

Python SDK (alternative):

from sports_skills import f1

schedule = f1.get_race_schedule(year=2025)
results = f1.get_race_results(year=2025, event="Monza")

CRITICAL: Before Any Query

CRITICAL: Before calling any data endpoint, verify:

• Year is derived from the system prompt's currentDate — never hardcoded.
• In January or February, use year = current_year - 1 (pre-season; the new F1 season has not started yet).

Choosing the Year

Derive the current year from the system prompt's date (e.g., currentDate: 2026-02-16 → current year is 2026).

• If the user specifies a year, use it as-is.
• If the user says "latest", "recent", "last season", or doesn't specify: The F1 season runs roughly March–December. If the current month is January or February, use year = current_year - 1. From March onward, use the current year.

Workflows

Race Weekend Analysis

1. get_race_schedule --year=<year> — find the event name and date 2. get_race_results --year=<year> --event=<name> — final classification (positions, times, points) 3. get_lap_data --year=<year> --event=<name> --session_type=R — lap-by-lap pace analysis 4. get_tire_analysis --year=<year> --event=<name> — strategy breakdown (compounds, stint lengths, degradation)

Driver/Team Comparison

1. get_championship_standings --year=<year> — championship context (points, wins, podiums) 2. get_team_comparison --year=<year> --team1=<t1> --team2=<t2> OR get_driver_comparison --year=<year> --driver1=<d1> --driver2=<d2> 3. get_season_stats --year=<year> — aggregate performance (fastest laps, top speeds)

Season Overview

1. get_race_schedule --year=<year> — full calendar with dates and circuits 2. get_championship_standings --year=<year> — driver and constructor standings 3. get_season_stats --year=<year> — season-wide fastest laps, top speeds, points leaders 4. get_driver_info --year=<year> — current grid (driver numbers, teams, nationalities)

Commands

See references/api-reference.md for full parameter lists and return shapes.

Examples

Example 1: F1 calendar User says: "Show me the F1 calendar" Actions: 1. Derive year from currentDate 2. Call get_race_schedule(year=<derived_year>) Result: Full calendar with event names, dates, and circuits

Example 2: Driver race performance User says: "How did Verstappen do at Monza?" Actions: 1. Derive year from currentDate (or from context) 2. Call get_race_results(year=<year>, event="Monza") for final classification 3. Call get_lap_data(year=<year>, event="Monza", session_type="R", driver="VER") for lap times Result: Finishing position, gap to leader, fastest lap, and tire strategy

Example 3: Latest results queried in pre-season User says: "What were the latest F1 results?" (asked in February 2026) Actions: 1. Current month is February → season not yet started → use year = 2025 2. Call get_race_schedule(year=2025) to find the last event of that season 3. Call get_race_results(year=2025, event=<last_event>) for the final race results Result: Results of the final 2025 race

Commands that DO NOT exist — never call these

• ~~get_qualifying~~ / ~~get_practice~~ — does not exist. Use get_session_data with session_type="Q" for qualifying or session_type="FP1"/"FP2"/"FP3" for practice.
• ~~get_standings~~ — does not exist. Use get_championship_standings instead.
• ~~get_results~~ — does not exist. Use get_race_results instead.
• ~~get_calendar~~ — does not exist. Use get_race_schedule instead.

If a command is not listed in the Commands table above, it does not exist.

Troubleshooting

Error: Event name not found Cause: Event name spelling does not match FastF1's internal naming Solution: Call get_race_schedule(year=<year>) first to get the exact event names, then retry with the correct name

Error: Session data is empty Cause: The session has not happened yet Solution: FastF1 only returns data for completed sessions. Check get_race_schedule for when the session is scheduled

Error: get_race_results returns no fastest_lap_time Cause: Some races do not include fastest lap data in the results endpoint Solution: Use get_lap_data(session_type="R") and find the minimum lap_time across all drivers

Error: Querying the current year in January or February returns no data Cause: The new F1 season has not started yet Solution: Use year = current_year - 1 for any pre-March query; do not query the current year before March

FastF1 — API Reference

Commands

See references/commands.md and references/schemas.md for detailed parameter descriptions and return schemas.

Session Types

Year Selection Rules

The F1 season runs roughly March–December.

• January or February: Use year = current_year - 1 (pre-season; new season not started).
• March onward: Use current_year (season has started or is imminent).
• Always derive from the system prompt's currentDate.

FastF1 — Valid Commands & Common Mistakes

Valid Commands

These are the ONLY valid commands. Do not invent or guess command names:

• get_race_schedule
• get_race_results
• get_session_data
• get_driver_info
• get_team_info
• get_lap_data
• get_pit_stops
• get_speed_data
• get_championship_standings
• get_season_stats
• get_team_comparison
• get_driver_comparison
• get_tire_analysis

Commands That DO NOT Exist (Commonly Hallucinated)

• ~~get_driver_results~~ — use get_race_results and filter by driver, or use get_lap_data with the driver parameter.
• ~~get_standings~~ — use get_championship_standings.
• ~~get_fastest_laps~~ — use get_lap_data and find the minimum lap_time, or use get_season_stats for season-wide fastest laps.
• ~~get_tire_strategy~~ — use get_tire_analysis for full tire strategy and degradation data.
• ~~get_circuit_info~~ — circuit details are included in get_race_schedule output.

If you're unsure whether a command exists, check this list. Do not try commands that aren't listed above.

Command Parameter Reference

get_race_schedule

• year (int, required): Season year

get_race_results

• year (int, required): Season year
• event (str, required): Event name (e.g., "Monza", "Silverstone")

get_session_data

• session_year (int, required): Year
• session_name (str, required): Event name
• session_type (str, optional): "Q" (qualifying), "R" (race), "FP1", etc. Default: "Q"

get_driver_info

• year (int, required): Season year
• driver (str, optional): Driver code or name. Omit for all drivers.

get_team_info

• year (int, required): Season year
• team (str, optional): Team name. Omit for all teams.

get_lap_data

• year (int, required): Season year
• event (str, required): Event name
• session_type (str, optional): Session type. Default: "R"
• driver (str, optional): Driver code. Omit for all drivers.

get_pit_stops

• year (int, required): Season year
• event (str, optional): Event name. Omit for full season.
• driver (str, optional): Driver code. Omit for all drivers.

get_speed_data

• year (int, required): Season year
• event (str, optional): Event name. Omit for full season.
• driver (str, optional): Driver code. Omit for all drivers.

get_championship_standings

• year (int, required): Season year

get_season_stats

• year (int, required): Season year

get_team_comparison

• year (int, required): Season year
• team1 (str, required): First team name (e.g., "Red Bull")
• team2 (str, required): Second team name (e.g., "McLaren")
• event (str, optional): Event name. Omit for full season.

get_driver_comparison

• year (int, required): Season year
• driver1 (str, required): Driver code or name (e.g., "NOR", "Norris")
• driver2 (str, required): Driver code or name (e.g., "PIA", "Piastri")
• event (str, optional): Event name. Omit for full season. Supports "last" for most recent race.

get_tire_analysis

• year (int, required): Season year
• event (str, optional): Event name. Omit for full season.
• driver (str, optional): Driver code. Omit for all drivers.

FastF1 — Return Schemas

get_race_results

Returns data[] list. Fields: position (int), driver (abbreviation), full_name, team, grid_position (int), points (int), status, time, fastest_lap (bool), fastest_lap_time.

Note: fastest_lap and fastest_lap_time are not always populated by FastF1. To find the actual fastest lap, use get_lap_data() and find the minimum lap_time across all drivers.

get_driver_info

Returns data as a list of driver objects (not a dict). Fields: driver_number, driver_code, full_name, team_name, country_code, headshot_url.

get_team_info

Returns data as a list of team objects. Fields: team_name, team_color, drivers[].

get_championship_standings

Returns data.driver_standings[] with fields: position, driver_code, full_name, team, points, wins, podiums.

Returns data.constructor_standings[] with fields: position, team, points, wins.

get_race_schedule

Returns schedule entries with event names, dates, circuits, and session times.

get_session_data

Returns detailed session data including lap times, sector times, and speed trap data for qualifying, race, or practice sessions.

get_lap_data

Returns lap-by-lap timing data with lap numbers, lap times, sector times, and compound information.

get_pit_stops

Returns pit stop data with pit-in/pit-out times, durations, and lap numbers.

get_speed_data

Returns speed trap data with intermediate speeds, speed trap values, and finish line speeds.

get_season_stats

Returns aggregated season statistics: fastest laps, top speeds, points, wins, and podiums per driver/team.

get_team_comparison

Returns head-to-head comparison data: qualifying deltas, race pace differences, sector comparisons, and points.

get_driver_comparison

Returns head-to-head driver comparison data: qualifying H2H record, race H2H record, pace deltas, and per-race breakdowns. Works for teammates and cross-team matchups.

get_tire_analysis

Returns tire strategy data: compound usage, stint lengths, degradation rates, and pit stop strategies.