> For the complete documentation index, see [llms.txt](https://docs.sportmonks.com/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/how-to-build-a-drivers-championship-standings-table.md).

# How to Build a Drivers' Championship Standings Table

> **✅ Included in All Plans**
>
> The standings endpoints are included at no additional cost.
>
> Plans differ only in leagues and API call limits.
>
> [Compare plans →](https://www.sportmonks.com/football-api/plans-pricing/)

This guide shows you how to retrieve driver standings for a season and shape the response into a ranked championship table.

### When to use this

Use the driver standings endpoints when you want to:

* Display a live or historical drivers' championship table
* Show a driver's current position and points total
* Build a comparison view between drivers across a season

### How to retrieve the data

Use the `GET Driver Standings by Season ID` endpoint to fetch all driver standings for a specific season:

```http
GET https://api.sportmonks.com/v3/motorsport/standings/drivers/seasons/{season_id}
?api_token={your_token}
```

To enrich the response with driver details, add the `participant` include:

```http
GET https://api.sportmonks.com/v3/motorsport/standings/drivers/seasons/{season_id}
?api_token={your_token}&include=participant
```

The `participant` include returns the driver entity directly on each standing object, so you do not need a second request to resolve driver names or images.

You can go one level deeper to include the driver's nationality:

```http
GET https://api.sportmonks.com/v3/motorsport/standings/drivers/seasons/{season_id}
?api_token={your_token}&include=participant.country
```

The maximum include depth on this endpoint is `2`.

### Working with the data

Each object in the `data` array represents one driver's standing for the season:

```json
{
  "id": 253776,
  "participant_id": 37920805,
  "sport_id": 2,
  "league_id": 3468,
  "season_id": 25273,
  "stage_id": 77476104,
  "position": 1,
  "points": 234,
  "participant": {
    "id": 37920805,
    "display_name": "Oscar Piastri",
    "image_path": "https://cdn.sportmonks.com/..."
  }
}
```

To render a sorted standings table, sort the array by `position` ascending:

```javascript
const API_TOKEN = 'your_token';
const SEASON_ID = 25273;

const response = await fetch(
  `https://api.sportmonks.com/v3/motorsport/standings/drivers/seasons/${SEASON_ID}?api_token=${API_TOKEN}&include=participant`
);
const { data } = await response.json();

// Sort by position in case the API returns entries out of order
const sorted = data.sort((a, b) => a.position - b.position);

// Calculate the gap to the leader
const leaderPoints = sorted[0].points;

const table = sorted.map(entry => ({
  position: entry.position,
  driver: entry.participant.display_name,
  points: entry.points,
  gap: entry.points === leaderPoints ? '-' : `+${leaderPoints - entry.points}`
}));

console.table(table);
```

<figure><img src="/files/IrXJgcQ9DxWhPK0mIPIR" alt=""><figcaption></figcaption></figure>

### Common pitfalls

**The response is not always ordered by position.** The API does not guarantee position-ascending order. Always sort by `position` in your application before rendering.

**`participant_id` refers to a driver, not a team.** On the driver standings endpoints, `participant_id` resolves to the Driver entity. Use the `participant` include rather than making a separate request to the drivers endpoint.

**`result`, `group_id`, `round_id`, and `standing_rule_id` are not used in the Motorsport API.** You can safely ignore these fields in your data model.

### Advanced usage

To display standings mid-season and show how they changed after the last race, store a snapshot of the previous response and compare `position` values between snapshots to calculate position changes.

To display standings for a historical season, simply change the `season_id` in the URL. Use the `GET All Seasons` endpoint (`/v3/motorsport/seasons`) to find the ID for a specific year.

### Common errors

| Status | Likely cause                                         |
| ------ | ---------------------------------------------------- |
| `401`  | Missing or invalid `api_token`                       |
| `404`  | The `season_id` does not exist in the Motorsport API |
| `429`  | Rate limit exceeded for your plan                    |

### See Also

**Standings endpoints**

* [GET All Driver Standings](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/standings/get-all-driver-standings.md)
* [GET Driver Standings by Season ID](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/standings/get-driver-standings-by-season-id.md)

**Related entities**

* [Standing](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/standing.md)
* [Driver](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/driver.md)
* [Season](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/season.md)

**Related guides**

* [How to Build a Constructors' Championship Standings Table](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/how-to-build-a-constructors-championship-standings-table.md)

### FAQ

**Which season ID should I use for the current Formula 1 season?** Use the `GET All Seasons` endpoint to retrieve all available seasons and their IDs. The `is_current` field on each season object indicates the active season.

**Can I retrieve standings for a single driver only?** No. The standings endpoint returns all drivers for the given season. Filter the response client-side by `participant_id` if you only need one driver's entry.

**Does the standings data update in real time during a race?** Standings update after each race concludes, not lap by lap. For live race positions, use the livescores endpoint with the `results` or `lineups.details` includes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/how-to-build-a-drivers-championship-standings-table.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.