> 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/tutorials/drivers-and-teams/drivers.md).

# Drivers

This guide covers how to retrieve driver data, enrich it with country, team, and metadata, and use it to build driver profiles and session-level driver lookups.

#### When to use this

Use the Drivers endpoints when you want to:

* Build a driver profile page with headshot, nationality, and career metadata
* List all drivers in your subscription
* Search for a driver by name
* Resolve a driver's team for a specific season
* Get a driver's three-letter short name or debut information

#### Important: Driver and Player

In the Sportmonks data model, Driver is an alias for the `player` entity. The entity behaves identically to `player` in other sports. This means:

* Filters use the `player` prefix: `playerCountries`, not `driverCountries`
* The driver's ID is referred to as `player_id` in lineup, result, lap, pitstop, and stint responses
* The endpoint path uses `/drivers/`, but the underlying entity is `player`

#### The Driver entity fields

<table data-search="false"><thead><tr><th>Field</th><th>Description</th><th>Type</th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique ID of the driver (same as <code>player_id</code> in other responses)</td><td>integer</td></tr><tr><td><code>sport_id</code></td><td>Sport ID</td><td>integer</td></tr><tr><td><code>country_id</code></td><td>Country of birth</td><td>integer</td></tr><tr><td><code>nationality_id</code></td><td>Nationality the driver represents</td><td>integer</td></tr><tr><td><code>city_id</code></td><td>City of birth</td><td>integer</td></tr><tr><td><code>position_id</code></td><td>Position within the team (first, second, or test driver)</td><td>integer</td></tr><tr><td><code>common_name</code></td><td>The name the driver is commonly known by</td><td>string</td></tr><tr><td><code>firstname</code></td><td>First name</td><td>string</td></tr><tr><td><code>lastname</code></td><td>Last name</td><td>string</td></tr><tr><td><code>name</code></td><td>Full name</td><td>string</td></tr><tr><td><code>display_name</code></td><td>Name recommended for display in applications</td><td>string</td></tr><tr><td><code>image_path</code></td><td>URL to the driver headshot</td><td>string</td></tr><tr><td><code>height</code></td><td>Height in centimetres</td><td>integer</td></tr><tr><td><code>weight</code></td><td>Weight in kilograms</td><td>integer</td></tr><tr><td><code>date_of_birth</code></td><td>Date of birth</td><td>string</td></tr><tr><td><code>gender</code></td><td>Gender</td><td>string</td></tr></tbody></table>

`detailed_position_id` and `type_id` are not used in the Motorsport API.

#### Available includes

`sport` `country` `city` `nationality` `teams` `latest` `position` `lineups` `metadata` `seasonDetails` `seasonTeams`

#### Retrieving drivers

Get all drivers in your subscription:

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

Get a single driver by ID:

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

Search drivers by name:

```http
GET https://api.sportmonks.com/v3/motorsport/drivers/search/{name}
?api_token={your_token}
```

Filter drivers by country:

```http
GET https://api.sportmonks.com/v3/motorsport/drivers
?api_token={your_token}&filters=playerCountries:{country_id}
```

#### Driver metadata

The `metadata` include returns driver-level data typed by ID. The confirmed driver metadata types are:

| ID       | Developer Name | Description                                        |
| -------- | -------------- | -------------------------------------------------- |
| `109851` | `DEBUT_SEASON` | Debut season year                                  |
| `109852` | `DEBUT_TRACK`  | Track name the driver debuted at                   |
| `109853` | `DEBUT_RESULT` | Debut finishing position or status (e.g. P14, DNF) |
| `109984` | `SHORT_NAME`   | Three-letter short name (e.g. HAM, VER)            |
| `110619` | `LEGACY_ID`    | The v1 driver ID for migration purposes            |

To include metadata:

```http
GET https://api.sportmonks.com/v3/motorsport/drivers/{driver_id}
?api_token={your_token}&include=metadata
```

#### Season-specific driver data

A driver's team and car number can change between seasons. Use `seasonDetails` to get season-specific assignments:

```http
GET https://api.sportmonks.com/v3/motorsport/drivers/{driver_id}
?api_token={your_token}&include=seasonTeams
```

Use `seasonTeams` to get which teams a driver has raced for across seasons, and `teams` for the current team association.

#### Working with the data

**Build a driver profile**

{% tabs %}
{% tab title="JavaScript" %}

```javascript
const API_TOKEN = 'your_token';

async function getDriverProfile(driverId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/drivers/${driverId}?api_token=${API_TOKEN}&include=country;nationality;metadata;teams`
  );
  const { data: driver } = await response.json();

  const metadataLookup = Object.fromEntries(
    (driver.metadata ?? []).map(m => [m.type_id, m.value])
  );

  return {
    name: driver.display_name,
    nationality: driver.nationality?.name ?? null,
    image: driver.image_path,
    shortName: metadataLookup[109984]?.short_name ?? null,
    debutSeason: metadataLookup[109851]?.season ?? null,
    debutTrack: metadataLookup[109852]?.track ?? null,
  };
}
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

API_TOKEN = "your_token"

def get_driver_profile(driver_id):
    url = f"https://api.sportmonks.com/v3/motorsport/drivers/{driver_id}"
    params = {
        "api_token": API_TOKEN,
        "include": "country;nationality;metadata;teams"
    }
    response = requests.get(url, params=params)
    driver = response.json()["data"]

    metadata_lookup = {m["type_id"]: m["value"] for m in driver.get("metadata", [])}

    return {
        "name": driver["display_name"],
        "nationality": driver["nationality"]["name"] if driver.get("nationality") else None,
        "image": driver["image_path"],
        "short_name": metadata_lookup.get(109984, {}).get("short_name"),
        "debut_season": metadata_lookup.get(109851, {}).get("season"),
        "debut_track": metadata_lookup.get(109852, {}).get("track"),
    }
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
function getDriverProfile(string $apiToken, int $driverId): array {
    $url = "https://api.sportmonks.com/v3/motorsport/drivers/{$driverId}
?api_token={$apiToken}&include=country;nationality;metadata;teams";
    $driver = json_decode(file_get_contents($url), true)['data'];

    $metadataLookup = [];
    foreach ($driver['metadata'] ?? [] as $m) {
        $metadataLookup[$m['type_id']] = $m['value'];
    }

    return [
        'name' => $driver['display_name'],
        'nationality' => $driver['nationality']['name'] ?? null,
        'image' => $driver['image_path'],
        'short_name' => $metadataLookup[109984]['short_name'] ?? null,
        'debut_season' => $metadataLookup[109851]['season'] ?? null,
        'debut_track' => $metadataLookup[109852]['track'] ?? null,
    ];
}
```

{% endtab %}
{% endtabs %}

**Search for a driver by name**

{% tabs %}
{% tab title="JavaScript" %}

```javascript
async function searchDriver(name) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/drivers/search/
     ${encodeURIComponent(name)}?api_token=${API_TOKEN}`
  );
  const { data } = await response.json();
  return data;
}
```

{% endtab %}

{% tab title="Python" %}

```python
def search_driver(name):
    url = f"https://api.sportmonks.com/v3/motorsport/drivers/search/{name}"
    params = {"api_token": API_TOKEN}
    response = requests.get(url, params=params)
    return response.json()["data"]
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
const API_TOKEN = 'YOUR_TOKEN';
function search_driver($name) {
    $encodedName = urlencode($name);
    $url = "https://api.sportmonks.com/v3/motorsport/drivers/search/" . $encodedName;
    $params = [
        "api_token" => API_TOKEN
    ];
    $requestUrl = $url . "?" . http_build_query($params);
    $response = file_get_contents($requestUrl);
    if ($response === false) {
        return [];
    }
    $json = json_decode($response, true);
    return $json["data"] ?? [];
}
```

{% endtab %}
{% endtabs %}

**Resolve a driver ID from a lineup entry**

In lineup, result, lap, pitstop, and stint responses, the driver is identified by `player_id`, not `driver_id`. These are the same value. Build a lookup once per fixture and reuse it:

{% tabs %}
{% tab title="JavaScript" %}

```javascript
async function buildDriverLookup(driverIds) {
  const ids = driverIds.join(',');
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/drivers/multi/${ids}?api_token=${API_TOKEN}&select=id,display_name,image_path`
  );
  const { data } = await response.json();
  return new Map(data.map(d => [d.id, d]));
}
```

{% endtab %}

{% tab title="Python" %}

```python
def build_driver_lookup(driver_ids):
    ids = ",".join(str(i) for i in driver_ids)
    url = f"https://api.sportmonks.com/v3/motorsport/drivers/multi/{ids}"
    params = {
        "api_token": API_TOKEN,
        "select": "id,display_name,image_path"
    }
    response = requests.get(url, params=params)
    drivers = response.json()["data"]
    return {d["id"]: d for d in drivers}
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
const API_TOKEN = 'YOUR_TOKEN';
function build_driver_lookup($driverIds) {
    $ids = implode(",", array_map("strval", $driverIds));
    $url = "https://api.sportmonks.com/v3/motorsport/drivers/multi/" . $ids;
    $params = [
        "api_token" => API_TOKEN,
        "select" => "id,display_name,image_path"
    ];
    $requestUrl = $url . "?" . http_build_query($params);
    $response = file_get_contents($requestUrl);
    if ($response === false) {
        return [];
    }
    $json = json_decode($response, true);
    $drivers = $json["data"] ?? [];
    $lookup = [];
    foreach ($drivers as $driver) {
        if (isset($driver["id"])) {
            $lookup[$driver["id"]] = $driver;
        }
    }
    return $lookup;
}
```

{% endtab %}
{% endtabs %}

#### Common pitfalls

**Using `driverCountries` as a filter name.** Driver shares the `player` entity filters. The correct filter is `playerCountries`, not `driverCountries`.

**Treating `display_name` and `name` as the same.** `name` is the full legal name. `display_name` is the recommended name for UI display, which in motorsport contexts is typically the driver's last name only (e.g. "Hamilton" rather than "Lewis Hamilton"). Use `display_name` for race timing displays and `name` or `common_name` for full-name contexts.

**Matching by `driver_id` in lineup/result/lap responses.** These responses use `player_id`, not `driver_id`. Both values are the same integer, but the field name differs. Use `player_id` when joining with lineup or results data.

**Fetching `metadata` on every live poll.** Driver metadata (debut season, short name) is static reference data. Fetch it once per driver at startup and cache it locally.

**`detailed_position_id` and `type_id` are not used.** These fields exist for cross-sport compatibility and will always be null in motorsport responses.

#### Common errors

| Status | Likely cause                                                |
| ------ | ----------------------------------------------------------- |
| `401`  | Missing or invalid `api_token`                              |
| `404`  | The driver ID does not exist or is not in your subscription |

#### See also

**Related tutorials**

* [Lineups](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/enrich-your-response/lineups)
* [Teams](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/drivers-and-teams/teams)
* [Filter and select fields - Filtering](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/filter-and-select-fields/filtering)

**Reference**

* [Driver entity](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/driver.md)
* [Metadata and Per-Season Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/metadata-and-per-season-data-type-reference)

#### FAQ

**Why do lineup and result responses use `player_id` instead of `driver_id`?** Driver is an alias for the `player` entity. The underlying field name in responses is `player_id`. Both refer to the same unique integer ID.

**What is the difference between `country_id` and `nationality_id`?** `country_id` is the driver's country of birth. `nationality_id` is the nationality they have chosen to represent, which may differ. For a nationality flag on a driver card, use `nationality_id` and include `nationality`.

**How do I get a driver's three-letter code (e.g. HAM, VER)?** Include `metadata` and read the `SHORT_NAME` type (ID `109984`). The value object contains a `short_name` key.

**How do I find which team a driver raced for in a specific season?** Use the `seasonTeams` include on the driver. This returns the driver's team assignments per season rather than only the current team.


---

# 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/tutorials/drivers-and-teams/drivers.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.