> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sportsapipro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Motorsport V2 API Overview

> Enhanced Motorsport API: 94 endpoints for F1, MotoGP, IndyCar, F2, F3, Moto2, Moto3

## Base URL

```
https://api.sportsapipro.com/v2/motorsport
```

## Authentication

All requests require an `x-api-key` header:

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.sportsapipro.com/v2/motorsport/live
```

## Motorsport-Specific Notes

* **Events are races/sessions** — not matches. Each session (FP1, FP2, FP3, Qualifying, Sprint, Race) is a separate event
* **Race weekends** — 4-6 sessions per Grand Prix weekend (Friday-Sunday)
* **Categories** — Championship types (F1=36, MotoGP=1325, Moto2=1580, Moto3=1581, IndyCar=1527)
* **Score format** — Finishing positions (P1-P20+), championship points
* **Participants** — 20+ drivers/riders on track simultaneously
* **Off-weekends** — During breaks there may be 0 events

## Canonical IDs and Routing

Motorsport uses a different upstream namespace than team sports. Championships are
`unique-stage` (not `unique-tournament`), race weekends are `stage` (not `event`),
and both drivers and constructors are accessed through `team/{id}`.

| Concept                       | Path                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------ |
| Championship (e.g. Formula 1) | `/api/motorsport/unique-stage/{uniqueStageId}`                                 |
| Category championships list   | `/api/motorsport/category/{categoryId}/unique-stages`                          |
| Race weekend / event          | `/api/motorsport/match/{stageId}` (+ `/substages` for sessions)                |
| Driver or constructor profile | `/api/motorsport/team/{teamId}`                                                |
| Race calendar                 | `/api/motorsport/tournament/{uniqueStageId}/season/{seasonId}/races`           |
| Recent results for a driver   | `/api/motorsport/players/{driverId}/events/last/0`                             |
| Drivers' Championship         | `/api/motorsport/tournament/{uniqueStageId}/season/{seasonId}/standings`       |
| Constructors' Championship    | `/api/motorsport/tournament/{uniqueStageId}/season/{seasonId}/standings/teams` |

### Key IDs to remember

| Series    | uniqueStage | category | Current season  |
| --------- | ----------- | -------- | --------------- |
| Formula 1 | `40`        | `36`     | 2026 = `214140` |
| MotoGP    | `17`        | `1325`   | —               |
| Moto2     | —           | `1580`   | —               |
| Moto3     | —           | `1581`   | —               |
| IndyCar   | —           | `1527`   | —               |

Example drivers: Max Verstappen = team `191417`. Example constructor: Red Bull Racing = team `214902`.

### Upstream limitations

These return empty or 404 by design — do not treat as bugs:

* `/sport/motorsport/scheduled-events/{date}` always returns an empty list (motorsport stages are not published in the date-scoped feed). Use the race calendar endpoint instead.
* Constructor teams (e.g. Red Bull Racing `214902`) do not expose `/events/last` or `/near-events`. Only driver "teams" do.
* Individual stage sub-endpoints (`/incidents`, `/lineups`, `/statistics`) return 404 for most stages — data is not available in the upstream feed.

## Race Weekend Structure

### Formula 1 (typical)

| Day      | Sessions                                           |
| -------- | -------------------------------------------------- |
| Friday   | Free Practice 1, Free Practice 2                   |
| Saturday | Free Practice 3, Qualifying (or Sprint Qualifying) |
| Sunday   | Sprint Race (some weekends), Grand Prix            |

### MotoGP (typical)

| Day      | Sessions                                 |
| -------- | ---------------------------------------- |
| Friday   | Free Practice 1, Free Practice 2         |
| Saturday | Free Practice 3, Qualifying, Sprint Race |
| Sunday   | Grand Prix                               |

## Championship Points (F1 2025+)

| Position                | Points        |
| ----------------------- | ------------- |
| P1                      | 25            |
| P2                      | 18            |
| P3                      | 15            |
| P4                      | 12            |
| P5                      | 10            |
| P6-P10                  | 8, 6, 4, 2, 1 |
| Fastest Lap (if top 10) | +1            |

## Key Motorsport Statistics

| Stat          | Description                      | Context                     |
| ------------- | -------------------------------- | --------------------------- |
| Lap Time      | Time to complete one lap         | Fastest lap is a key metric |
| Pit Stops     | Number and duration of pit stops | Strategy indicator          |
| Overtakes     | Position changes during race     | Excitement metric           |
| Grid Position | Starting position                | From qualifying             |
| Gap           | Time behind leader               | Shows race competitiveness  |
| DNF           | Did Not Finish                   | Retirement from race        |

## Endpoint Categories

| Category                  | Count  | Description                           |
| ------------------------- | ------ | ------------------------------------- |
| Live & Schedule           | 7      | Live sessions, schedules              |
| Search & Discovery        | 7      | Search, categories, news              |
| Tournament / Championship | 21     | Championship data, seasons, standings |
| Race / Event              | 23     | Race details, stats, odds             |
| Team / Constructor        | 12     | Constructor profiles, drivers         |
| Driver                    | 16     | Driver stats, career data             |
| Team Principal / Venue    | 8      | Principals, circuits                  |
| **Total**                 | **94** |                                       |

## Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.sportsapipro.com/v2/motorsport/live" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.sportsapipro.com/v2/motorsport/live',
    { headers: { 'x-api-key': 'YOUR_API_KEY' } }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.sportsapipro.com/v2/motorsport/live',
      headers={'x-api-key': 'YOUR_API_KEY'}
  )
  data = response.json()
  ```
</CodeGroup>

## UI Design Ideas

* **Starting grid view**: Use `/match/{id}/lineups` — show grid positions (pole position highlighted)
* **Race results**: Show finishing order with gaps ("+5.2s", "+1 lap", "DNF")
* **Championship standings**: Two standings — Drivers Championship and Constructors Championship
* **Race calendar**: Show full season calendar with circuits — use `.../rounds` + `.../venues`
* **Lap chart**: Use `/match/{id}/graph` — show position changes lap-by-lap
* **Team colors**: F1 teams have distinctive colors — display branding prominently
* **Session types**: Clearly label Practice/Qualifying/Sprint/Race — very different contexts
* **DNF/DNS**: Handle "Did Not Finish" and "Did Not Start" statuses
* **Fastest lap**: Show which driver set it — prestigious stat
* **Weather**: Rain transforms races — show prominently if available

## MotoGP Championship Points

| Position | Points           |
| -------- | ---------------- |
| P1       | 25               |
| P2       | 20               |
| P3       | 16               |
| P4-P15   | Decreasing scale |

## Sport Comparison — Motorsport vs Other Sports

| Feature          | Motorsport                              | Football        | Tennis            |
| ---------------- | --------------------------------------- | --------------- | ----------------- |
| Event type       | Race (20+ drivers/riders)               | Match (2 teams) | Match (2 players) |
| Scoring          | Finishing position, championship points | Goals           | Sets/games        |
| Duration         | Race: 1-2 hrs; Weekend: Fri-Sun         | \~90 min        | 1-5 hours         |
| Key stats        | Lap times, pit stops, overtakes         | Goals, assists  | Aces, winners     |
| Participants     | 20+ on track simultaneously             | 22 (11v11)      | 2                 |
| Season structure | Race calendar (20-24 Grand Prix)        | League + cups   | Tour events       |