Skip to main content

​
Response Structure

All API endpoints return JSON responses with appropriate HTTP status codes. Successful responses return 200 OK with the requested data, while errors return appropriate error codes with error details.

​
Success Responses

​
Standard Success Format

Most endpoints return a JSON object with response-specific fields: 
{
  "field1": "value1",
  "field2": "value2",
  "nested_object": {
    "key": "value"
  },
  "array_field": [1, 2, 3]
}

{
  "probability": 0.8247,
  "prediction": "Top-3 Likely",
  "insights": "P1 in dry on soft tires = Excellent podium chances!"
}
​
probability
float
required
Decimal value between 0.0 and 1.0 representing podium finish probability
​
prediction
string
required
Human-readable prediction outcome (“Top-3 Likely” or “Top-3 Unlikely”)
​
insights
string
required
Contextual analysis of the prediction based on input parameters

​
Error Responses

​
Error Response Format

Error responses include an error field with a descriptive message: 
{
  "error": "Description of what went wrong"
}

​
HTTP Status Codes

​
200
OK
Request succeeded. Response contains requested data.
​
500
Internal Server Error
Server-side error occurred. Common causes:
  • ML model not loaded
  • Required data files missing
  • Race simulation engine error

​
Common Error Scenarios

{
  "error": "Model not loaded"
}
Some endpoints require data generation scripts to be run before they can return results. Check the error message for specific instructions.

​
Data Types

​
Primitive Types

​
string
string
Text values, UTF-8 encoded. Examples: driver names, team names, weather conditions.
​
integer
integer
Whole numbers. Examples: grid positions (1-20), points, wins, laps.
​
float
float
Decimal numbers. Examples: probabilities (0.0-1.0), lap times, time gaps.
​
boolean
boolean
True/false values. Examples: DNF status, wet race indicator.
​
array
array
Ordered list of values. Can contain primitives or objects. Examples: driver lists, statistics arrays.
​
object
object
Key-value pairs (JSON object). Examples: driver details, race results.

​
Enumerated Values

Certain fields accept only specific predefined values:

​
Weather Types

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

​
Tire Compounds

  • SOFT - Soft compound (fastest, high degradation)
  • MEDIUM - Medium compound (balanced)
  • HARD - Hard compound (slowest, low degradation)

​
Circuit Types

  • STANDARD - Standard racing circuit
  • STREET - Street circuit (Monaco-style)
  • FAST - High-speed circuit (Monza-style)
  • DESERT - Desert circuit
  • TECHNICAL - Technical circuit with tight corners

​
Driver Codes (3-letter)

Red Bull Racing: VER, LAW
Ferrari: HAM, LEC
McLaren: NOR, PIA
Mercedes: RUS, ANT
Aston Martin: ALO, STR
Alpine: GAS, DOO
Williams: SAI, ALB
Haas: OCO, BEA
Racing Bulls: TSU, HAD
Sauber: HUL, BOR

​
Complex Response Objects

​
Driver Result Object

Returned in lap-by-lap race simulations: 
{
  "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, 2, 1],
  "color": "#1E41FF",
  "events": [
    "Pit stop on L18: SOFT → MEDIUM",
    "Fastest lap on L42"
  ]
}
​
position
integer
required
Final finishing position (1-20)
​
name
string
required
Driver’s full name
​
team
string
required
Team/constructor name
​
gap
float
required
Time gap to winner in seconds (0.0 for winner)
​
dnf
boolean
required
Whether driver retired from the race
​
dnf_lap
integer
Lap number where DNF occurred (null if finished)
​
tires_used
array<string>
required
Tire compounds used during race in order (e.g., [“SOFT”, “MEDIUM”, “HARD”])
​
pit_laps
array<integer>
required
Lap numbers where pit stops occurred
​
laps_led
integer
required
Number of laps spent in P1
​
positions
array<integer>
required
Position at each lap for position chart visualization
​
color
string
required
Team color as hex code (e.g., “#1E41FF”)
​
events
array<string>
required
Notable events for this driver (pit stops, penalties, overtakes)

​
Championship Standing Object

Returned in season predictions: 
{
  "name": "Max Verstappen",
  "team": "Red Bull Racing",
  "points": 425,
  "wins": 15,
  "podiums": 20,
  "dnfs": 1
}
​
name
string
required
Driver’s full name
​
team
string
required
Team name
​
points
integer
required
Total championship points
​
wins
integer
required
Number of race victories
​
podiums
integer
required
Number of top-3 finishes
​
dnfs
integer
required
Number of retirements

​
Race Result Object

Returned in 2026 season predictions: 
{
  "round": 1,
  "race": "Bahrain Grand Prix",
  "weather": "DRY",
  "winner": "Max Verstappen",
  "p2": "Lewis Hamilton",
  "p3": "Charles Leclerc",
  "dnfs": 2
}
​
round
integer
required
Race number in championship (1-24)
​
race
string
required
Grand Prix name
​
weather
string
required
Weather conditions (DRY, LIGHT_RAIN, HEAVY_RAIN)
​
winner
string
required
Race winner’s name
​
p2
string
required
Second place driver
​
p3
string
required
Third place driver
​
dnfs
integer
required
Number of DNFs in this race

​
Request Headers

No special headers are required for API requests. Standard HTTP headers are sufficient: 
GET /api/predict_v2?grid=1&weather=DRY HTTP/1.1
Host: localhost:5000

​
CORS Policy

The Flask application runs in development mode with default CORS settings. Cross-origin requests may require additional configuration in production environments.

​
Rate Limiting

No rate limiting is currently implemented. The API is designed for local development and testing.
For production deployments, consider implementing rate limiting and authentication mechanisms.

​
Response Times

Endpoint Performance

Fast Endpoints (< 100ms)
  • /api/predict_v2 - Simple model inference
  • /api/feature_importance - Cached feature data
  • /api/simulate_race - Basic randomization
Medium Endpoints (100ms - 1s)
  • /api/compare - File read + processing
  • /api/season_2026 - File read + parsing
Slow Endpoints (1s - 5s)
  • /api/lap_race - Full race simulation with 50 laps
  • /api/simulate_championship - Multiple race simulations
The /api/lap_race endpoint is the most computationally intensive as it simulates every lap with pit stops, tire degradation, and random events. Consider implementing caching for frequently requested simulations.

​
Content-Type

All responses have Content-Type: application/json header. 
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1234

{
  "probability": 0.8247,
  "prediction": "Top-3 Likely"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us