API Documentation | F1 Companion API

GET / API landing page ▼

Returns the HTML landing page with links to all available endpoints. This is the interactive homepage you see when visiting the API root.

ℹ️ This endpoint returns HTML, not JSON. All other endpoints return JSON.

GET /health API health check ▼

Returns the API health status, version, server uptime, and the reachability of external dependencies (Jolpica Ergast API).

Example Response

JSON

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime_seconds": 3600,
  "dependencies": {
    "jolpica_ergast_api": "online"
  }
}

ℹ️ Status is "healthy" when all dependencies are online, or "degraded" if any external API is unreachable.

GET /schedule Full season calendar ▼

Returns the complete season race calendar with all session times (practice, qualifying, sprint, race) and whether each race has been completed.

Example Response

JSON

{
  "season": "2026",
  "races": 24,
  "schedule": [
    {
      "round": "1",
      "racename": "Bahrain Grand Prix",
      "circuitid": "bahrain",
      "circuitname": "Bahrain International Circuit",
      "circuitlocation": "Sakhir",
      "circuitcountry": "Bahrain",
      "GrandPrix": "2026-03-08",
      "time": "15:00:00Z",
      "is_completed": true,
      "FirstPractice": { "date": "2026-03-06", "time": "11:30:00Z" },
      "Qualifying": { "date": "2026-03-07", "time": "15:00:00Z" }
    }
  ]
}

GET /next_race Live countdown & weather ▼

Returns the next upcoming race with a live countdown to the next session, current track weather via Open-Meteo, sprint weekend detection, and awareness of any currently ongoing session.

Example Response

JSON

{
  "round": "5",
  "race_name": "Spanish Grand Prix",
  "circuit": "Circuit de Barcelona-Catalunya",
  "country": "Spain",
  "flag_emoji": "🇪🇸",
  "weather": {
    "temp": "28°C",
    "condition": "Clear Sky"
  },
  "countdown": {
    "days": 2,
    "hours": 5,
    "minutes": 30,
    "seconds": 15
  },
  "next_session": "Session Name : Qualifying  Time Zone : UTC 2026-06-20 14:00 UTC",
  "ongoing_session": null,
  "is_sprint_weekend": false
}

GET /circuits All circuit details ▼

Returns information on all circuits in the current season, including track layout image URLs hosted on GitHub.

Example Response

JSON

{
  "season": "2026",
  "total_circuits": 24,
  "circuits": [
    {
      "circuitid": "bahrain",
      "circuitname": "Bahrain International Circuit",
      "circuitlocation": "Sakhir",
      "circuitcountry": "Bahrain",
      "circuitlayout": "https://github.com/.../sakhir-bahrain2026.webp?raw=true"
    }
  ]
}

GET /drivers Current driver lineup ▼

Returns a lightweight list of all official drivers in the current season. Filtered to only include confirmed 2026 grid drivers.

Example Response

JSON

{
  "season": "2026",
  "total_drivers": 22,
  "drivers": [
    {
      "driverid": "max_verstappen",
      "firstname": "Max",
      "lastname": "Verstappen",
      "nationality": "Dutch",
      "number": "1",
      "code": "VER"
    }
  ]
}

GET /driver_profile Enriched profiles & career stats ▼

Returns enriched driver profiles combining identity, headshot image, current team, and full career statistics — including world championships, total wins, poles, podiums, career points, and a round-by-round points progression for the current season.

Example Response

JSON

{
  "season": "2026",
  "total_drivers": 22,
  "driver_profiles": [
    {
      "driver_id": "max_verstappen",
      "driver_name": "Max Verstappen",
      "driver_code": "VER",
      "driver_number": "1",
      "nationality": "Dutch",
      "driver_image": "https://...",
      "team": "Red Bull",
      "career_stats": {
        "world_championships": 4,
        "total_races": 240,
        "total_pole": 50,
        "total_wins": 75,
        "total_podiums": 130,
        "career_points": 3500.0,
        "total_seasons": 12,
        "current_season": { "position": "1", "points": "200" }
      },
      "points_progression": [
        { "round": "1", "points": 25.0, "cumulative": 25.0 }
      ]
    }
  ]
}

GET /constructors Current team lineup ▼

Returns a lightweight list of all constructors (teams) in the current season.

Example Response

JSON

{
  "season": "2026",
  "total_constructors": 11,
  "constructors": [
    {
      "constructorid": "red_bull",
      "name": "Red Bull",
      "nationality": "Austrian",
      "url": "http://en.wikipedia.org/wiki/Red_Bull_Racing"
    }
  ]
}

GET /constructor_profile Enriched profiles & history ▼

Returns enriched constructor profiles combining identity, logo, car image, current driver lineup, and full career statistics — including championships, total wins, podiums, and a round-by-round points progression for the current season.

Example Response

JSON

{
  "season": "2026",
  "total_constructors": 11,
  "constructor_profiles": [
    {
      "constructor_id": "red_bull",
      "constructor_name": "Red Bull",
      "constructor_logo": "https://...",
      "constructor_car": "https://...",
      "drivers": ["Max Verstappen", "Liam Lawson"],
      "stats": {
        "constructor_championships": 6,
        "driver_championships": 7,
        "total_races": 390,
        "wins": 135,
        "podiums": 290
      },
      "points_progression": [
        { "round": "1", "points": 40.0, "cumulative": 40.0 }
      ]
    }
  ]
}

GET /constructor_stats All-time team stats ▼

Returns all-time statistics for every constructor on the current grid, including win/podium percentages and current season standing.

Example Response

JSON

{
  "season": "2026",
  "total_constructors": 11,
  "constructor_stats": [
    {
      "constructor_id": "ferrari",
      "constructor_name": "Ferrari",
      "stats": {
        "constructor_championships": 16,
        "driver_championships": 15,
        "total_races": 1130,
        "wins": 250,
        "win_percentage": "22.12%",
        "podiums": 820,
        "podium_percentage": "36.28%",
        "current_season": {
          "year": "2026",
          "position": "2",
          "points": "200"
        }
      }
    }
  ]
}

GET /driver_standings Live WDC standings ▼

Returns the live World Drivers' Championship standings for the current season.

Example Response

JSON

{
  "season": "2026",
  "status": "SEASON IN PROGRESS",
  "total_drivers": 22,
  "drivers": [
    {
      "position": "1",
      "points": "200",
      "driverid": "max_verstappen",
      "name": "Max Verstappen",
      "team_name": "Red Bull",
      "nationality": "Dutch",
      "url": "https://en.wikipedia.org/wiki/Max_Verstappen"
    }
  ]
}

ℹ️ Returns "status": "SEASON IS YET TO BEGIN" with an empty list if no races have been completed.

GET /constructor_standings Live WCC standings ▼

Returns the live World Constructors' Championship standings, including each team's current driver lineup.

Example Response

JSON

{
  "season": "2026",
  "status": "SEASON IN PROGRESS",
  "total_teams": 11,
  "constructors": [
    {
      "position": "1",
      "points": "400",
      "name": "Red Bull",
      "drivers": ["Max Verstappen", "Liam Lawson"],
      "nationality": "Austrian"
    }
  ]
}

GET /teammate_h2h Head-to-head comparisons ▼

Returns comprehensive head-to-head comparison stats for all teammate pairs on the current grid. Covers qualifying, sprint qualifying, sprint race, main race, and championship standings delta — with per-round breakdown.

Example Response

JSON

{
  "season": "2026",
  "total_teams": 10,
  "head_to_head": [
    {
      "constructor": "Red Bull",
      "constructor_id": "red_bull",
      "constructor_logo": "https://...",
      "drivers": {
        "driver_a": { "driver_id": "lawson", "name": "Liam Lawson" },
        "driver_b": { "driver_id": "max_verstappen", "name": "Max Verstappen" }
      },
      "qualifying": {
        "driver_a_wins": 0,
        "driver_b_wins": 5,
        "ties": 0,
        "total_completed": 5
      },
      "race": { "driver_a_wins": 1, "driver_b_wins": 4, "ties": 0 },
      "standings": {
        "driver_a": { "position": "8", "points": "50" },
        "driver_b": { "position": "1", "points": "200" },
        "points_delta": 150.0
      }
    }
  ]
}

GET /race_results/{round}/{year} Race results by round ▼

Returns detailed race results for a specific round and year, including grid position, finishing status, race time, and fastest lap.

Path Parameters

Name	Type	Description
`round` required	string	Race round number (e.g., `1`)
`year` required	string	Season year (e.g., `2025`)

Example Response

JSON

{
  "season": "2025",
  "round": "1",
  "race_name": "Australian Grand Prix",
  "results": [
    {
      "position": "1",
      "positionText": "1",
      "driver": "Lando Norris",
      "driver_image": "https://...",
      "constructor": "McLaren",
      "points": "25",
      "grid": "1",
      "status": "Finished",
      "time": "1:24:28.476",
      "fastest_lap_time": "1:21.300"
    }
  ]
}

ℹ️ Returns "status": "RESULT NOT YET AVAILABLE" if the race hasn't taken place. The positionText field uses "R" for retired and "D" for disqualified drivers.

GET /qualifying_results/{round}/{year} Qualifying results by round ▼

Returns qualifying session results with Q1, Q2, and Q3 lap times for a specific round and year.

Path Parameters

Name	Type	Description
`round` required	string	Race round number
`year` required	string	Season year

Example Response

JSON

{
  "season": "2025",
  "round": "1",
  "race_name": "Australian Grand Prix",
  "results": [
    {
      "position": "1",
      "driver": "Lando Norris",
      "driver_image": "https://...",
      "constructor": "McLaren",
      "q1": "1:22.123",
      "q2": "1:21.456",
      "q3": "1:20.789"
    }
  ]
}

GET /sprint_results/{round}/{year} Sprint results by round ▼

Returns sprint race results for a specific round and year. Only available for sprint weekends. Response schema matches /race_results.

Path Parameters

Name	Type	Description
`round` required	string	Race round number
`year` required	string	Season year

GET /sprint_qualifying_results/{round}/{year} Sprint qualifying by round ▼

Returns sprint qualifying results (derived from sprint grid positions) for a specific round and year. Only available for sprint weekends.

Path Parameters

Name	Type	Description
`round` required	string	Race round number
`year` required	string	Season year

GET /race_control ⚠️ Under Development ▼

Returns live and historical race control messages — flags, penalties, safety car deployments, investigations — from the OpenF1 API. This endpoint is not available in Vercel production (local development only).

Query Parameters

Name	Type	Default	Description
`session_key`	string	"latest"	Session key (e.g., `latest` or `9158`)

Example Response

JSON

{
  "session_key": "latest",
  "total_messages": 42,
  "messages": [
    {
      "timestamp": "2026-03-08T15:02:00",
      "category": "Flag",
      "message": "GREEN LIGHT - PIT EXIT OPEN",
      "flag": "GREEN",
      "driver_number": null,
      "lap_number": 1,
      "scope": "Track",
      "sector": null
    }
  ]
}

⚠️ This endpoint is excluded from Vercel production builds. It is only available when running the API locally.

GET /team-radio/latest Latest team radio ▼

Returns the team radio communications from the latest or ongoing session.

Query Parameters

Name	Type	Default	Description
`last_name`	string	null	Filter by driver's last name (e.g., Verstappen)

Example Response

JSON

{
  "session_key": "latest",
  "last_name": null,
  "total_messages": 1,
  "messages": [
    {
      "timestamp": "2026-03-08T15:05:00",
      "driver_number": 1,
      "recording_url": "https://...",
      "session_key": 9158
    }
  ]
}

GET /news Latest F1 news ▼

Returns the latest F1 news articles aggregated from multiple RSS sources (Formula 1, Sky Sports, Autosport). Articles are deduplicated and sorted by publish date, returning up to 10 articles.

Example Response

JSON

{
  "status": "ok",
  "articles": [
    {
      "title": "Verstappen takes pole in Spain",
      "link": "https://www.formula1.com/...",
      "summary": "Max Verstappen secured pole position with a blistering lap...",
      "published": "Sat, 21 Jun 2026 14:00:00 GMT",
      "source": "Formula 1"
    }
  ]
}