Flask API Endpoints

Overview

The F1 ML Prediction System exposes 7 REST API endpoints for race predictions, driver comparisons, and race simulations. All endpoints return JSON responses and use GET requests with query parameters. Base URL: http://localhost:5000

Winner Prediction V2

curl "http://localhost:5000/api/predict_v2?grid=1&weather=DRY&tire=SOFT&circuit=STANDARD"

Predicts podium finish probability based on grid position, weather conditions, tire compound, and circuit type using the enhanced V2 model.

Query Parameters

grid

integer

default:"1"

required

Starting grid position (1-20). Lower numbers indicate better starting positions.

1 = Pole position
2-10 = Top 10
11-20 = Back of grid

weather

string

default:"DRY"

required

Weather conditions for the race.

DRY - Sunny/dry conditions
LIGHT_RAIN - Light rain
HEAVY_RAIN - Heavy rain/storm

tire

string

default:"MEDIUM"

required

Starting tire compound.

SOFT - Fast but high degradation (0.08 sec/lap)
MEDIUM - Balanced performance (0.05 sec/lap)
HARD - Slow but consistent (0.03 sec/lap)

circuit

string

default:"STANDARD"

required

Circuit type/characteristics.

STANDARD - Standard racing circuit
STREET - Street circuit (Monaco, Singapore)
FAST - High-speed circuit (Monza, Spa)
DESERT - Desert circuit (Bahrain, Saudi Arabia)
TECHNICAL - Technical circuit

Response

probability

float

Probability of finishing in top 3 (0.0 to 1.0)

prediction

string

Human-readable prediction result.

"Top-3 Likely" if probability > 0.5
"Top-3 Unlikely" if probability ≤ 0.5

insights

string

Contextual insights based on input parameters and predicted probability.

Example Response

{
  "probability": 0.8247,
  "prediction": "Top-3 Likely",
  "insights": "P1 in dry on soft tires = Excellent podium chances!"
}

Lap-by-Lap Race Simulation

curl "http://localhost:5000/api/lap_race?weather=DRY&circuit=STANDARD"

Simulates a complete 50-lap race with realistic pit stops, tire degradation, safety cars, weather changes, and DNFs.

Query Parameters

weather

string

default:"DRY"

required

Starting weather conditions.

DRY - Dry conditions
LIGHT_RAIN - Light rain
HEAVY_RAIN - Heavy rain

circuit

string

default:"STANDARD"

required

Circuit type.

STANDARD - Standard circuit
STREET - Street circuit
FAST - High-speed circuit
DESERT - Desert circuit

Response

winner

string

Name of the race winner

results

array

Array of driver results (all 20 drivers)

Show Driver Result Object

position

integer

Final finishing position (1-20)

name

string

Driver’s full name

team

string

Team name

gap

float

Time gap to race winner in seconds

dnf

boolean

Whether the driver did not finish

dnf_lap

integer

Lap number where DNF occurred (if applicable)

tires_used

array

Array of tire compounds used during the race (e.g., [“SOFT”, “MEDIUM”])

pit_laps

array

Array of lap numbers where pit stops occurred

laps_led

integer

Number of laps spent in first position

positions

array

Position at each lap (for position chart)

color

string

Team color hex code for visualizations

events

array

Array of notable events for this driver (e.g., “Pit stop on L18”)

dnf_count

integer

Total number of DNFs in the race

sc_deployments

array

Array of lap numbers where safety car was deployed

weather_history

array

Array of [lap, weather] tuples showing weather changes throughout the race

fastest_lap

object

Show Fastest Lap Object

driver

string

Driver who set the fastest lap

time

float

Fastest lap time in seconds

Example Response

{
  "winner": "Max Verstappen",
  "dnf_count": 2,
  "sc_deployments": [12, 38],
  "weather_history": [[1, "DRY"], [25, "LIGHT_RAIN"]],
  "fastest_lap": {
    "driver": "Charles Leclerc",
    "time": 78.452
  },
  "results": [
    {
      "position": 1,
      "name": "Max Verstappen",
      "team": "Red Bull Racing",
      "gap": 0.0,
      "dnf": false,
      "dnf_lap": null,
      "tires_used": ["SOFT", "MEDIUM"],
      "pit_laps": [18],
      "laps_led": 45,
      "positions": [1, 1, 1],
      "color": "#1E41FF",
      "events": ["Pit stop on L18: SOFT → MEDIUM"]
    }
  ]
}

2026 Season Prediction

curl "http://localhost:5000/api/season_2026"

Returns AI-generated predictions for the complete 2026 F1 season including championship standings and all race results.

This endpoint requires season_2026_calendar.py to be run first to generate the prediction data file.

Query Parameters

None - this endpoint takes no parameters.

Response

standings

array

Championship standings for all drivers

Show Driver Standing Object

name

string

Driver’s full name

team

string

Team name

points

integer

Total championship points

wins

integer

Number of race wins

podiums

integer

Number of podium finishes

dnfs

integer

Number of DNFs

race_results

array

Results for all races in the 2026 season

Show Race Result Object

round

integer

Race round number (1-24)

race

string

Race/Grand Prix name

weather

string

Weather conditions for the race

winner

string

Race winner name

string

Second place driver

string

Third place driver

dnfs

integer

Number of DNFs in this race

Example Response

{
  "standings": [
    {
      "name": "Max Verstappen",
      "team": "Red Bull Racing",
      "points": 425,
      "wins": 15,
      "podiums": 20,
      "dnfs": 1
    }
  ],
  "race_results": [
    {
      "round": 1,
      "race": "Bahrain Grand Prix",
      "weather": "DRY",
      "winner": "Max Verstappen",
      "p2": "Lewis Hamilton",
      "p3": "Charles Leclerc",
      "dnfs": 2
    }
  ]
}

Error Response

{
  "error": "No 2026 predictions found. Run season_2026_calendar.py first!"
}

Driver Comparison

curl "http://localhost:5000/api/compare?driver1=VER&driver2=HAM"

Compares career statistics between two F1 drivers.

This endpoint requires driver_stats_real.py to be run first to generate the comparison data.

Query Parameters

driver1

string

default:"VER"

required

Three-letter driver code for first driver.Available drivers: VER, LAW, HAM, LEC, NOR, PIA, RUS, ANT, ALO, STR, GAS, DOO, SAI, ALB, OCO, BEA, TSU, HAD, HUL, BOR

driver2

string

default:"HAM"

required

Three-letter driver code for second driver.

Response

driver1_name

string

First driver’s full name

driver2_name

string

Second driver’s full name

driver1_team

string

First driver’s team

driver2_team

string

Second driver’s team

Example Response

{
  "driver1_name": "Max Verstappen",
  "driver2_name": "Lewis Hamilton",
  "driver1_team": "Red Bull Racing",
  "driver2_team": "Ferrari",
  "categories": ["Wins", "Podiums", "Poles", "Championships", "Wet Wins", "Street Wins"],
  "driver1_stats": [61, 107, 40, 3, 8, 12],
  "driver2_stats": [103, 197, 104, 7, 15, 20],
  "driver1_races": 183,
  "driver2_races": 334,
  "driver1_winrate": 33.3,
  "driver2_winrate": 30.8,
  "driver1_career_pts": 2586,
  "driver2_career_pts": 4583,
  "driver1_summary": "61 wins | 107 podiums | 3 titles | 33.3% win rate",
  "driver2_summary": "103 wins | 197 podiums | 7 titles | 30.8% win rate",
  "better_driver": "Lewis Hamilton"
}

Error Response

{
  "error": "Run driver_stats_real.py first"
}

Feature Importance

curl "http://localhost:5000/api/feature_importance"

Returns feature importance scores from the machine learning model, showing which factors most influence race predictions.

Query Parameters

None - this endpoint takes no parameters.

Response

features

array

Array of feature names sorted by importance (highest to lowest)

importance

array

Array of importance scores (0.0 to 1.0) corresponding to features

Example Response

{
  "features": [
    "GridPosition",
    "Driver_TotalWins",
    "Weather_Impact",
    "Tire_Degradation_Rate",
    "Team_TotalWins",
    "Circuit_Familiarity",
    "Driver_AvgPosition",
    "Is_Wet_Race",
    "Tire_Advantage",
    "Is_Street_Circuit"
  ],
  "importance": [
    0.2845,
    0.1632,
    0.1289,
    0.0987,
    0.0845,
    0.0723,
    0.0612,
    0.0501,
    0.0398,
    0.0168
  ]
}

Race Simulation

curl "http://localhost:5000/api/simulate_race?weather=DRY"

Simulates a basic race with randomized positions based on weather conditions.

Query Parameters

weather

string

default:"DRY"

Weather conditions affecting race randomization.

DRY - Standard simulation
RAIN - Increased randomization

Response

drivers

array

Array of driver codes in finishing order (1st to 20th)

positions

array

Array of position numbers corresponding to drivers

Example Response

{
  "drivers": ["VER", "HAM", "LEC", "SAI", "NOR"],
  "positions": [1, 2, 3, 4, 5]
}

Championship Simulation

curl "http://localhost:5000/api/simulate_championship"

Simulates a 5-race championship with points accumulation.

Query Parameters

None - this endpoint takes no parameters.

Response

standings

array

Championship standings after 5 races

Show Standing Object

driver

string

Three-letter driver code

points

integer

Total championship points

champion

string

Three-letter code of the championship winner

Example Response

{
  "standings": [
    {"driver": "VER", "points": 110},
    {"driver": "HAM", "points": 85},
    {"driver": "LEC", "points": 72},
    {"driver": "SAI", "points": 58},
    {"driver": "PER", "points": 45}
  ],
  "champion": "VER"
}

Machine Learning

Data Processing

Simulation

Web API

Overview

Winner Prediction V2

Query Parameters

Response

Example Response

Lap-by-Lap Race Simulation

Query Parameters

Response

Example Response

2026 Season Prediction

Query Parameters

Response

Example Response

Error Response

Driver Comparison

Query Parameters

Response

Example Response

Error Response

Feature Importance

Query Parameters

Response

Example Response

Race Simulation

Query Parameters

Response

Example Response

Championship Simulation

Query Parameters

Response

Example Response

Build docs developers (and LLMs) love

Machine Learning

Data Processing

Simulation

Web API

​Overview

​Winner Prediction V2

​Query Parameters

​Response

​Example Response

​Lap-by-Lap Race Simulation

​Query Parameters

​Response

​Example Response

​2026 Season Prediction

​Query Parameters

​Response

​Example Response

​Error Response

​Driver Comparison

​Query Parameters

​Response

​Example Response

​Error Response

​Feature Importance

​Query Parameters

​Response

​Example Response

​Race Simulation

​Query Parameters

​Response

​Example Response

​Championship Simulation

​Query Parameters

​Response

​Example Response

Build docs developers (and LLMs) love

Overview

Winner Prediction V2

Query Parameters

Response

Example Response

Lap-by-Lap Race Simulation

Query Parameters

Response

Example Response

2026 Season Prediction

Query Parameters

Response

Example Response

Error Response

Driver Comparison

Query Parameters

Response

Example Response

Error Response

Feature Importance

Query Parameters

Response

Example Response

Race Simulation

Query Parameters

Response

Example Response

Championship Simulation

Query Parameters

Response

Example Response