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

Field

Description

Type

id

Unique ID of the driver (same as player_id in other responses)

integer

sport_id

Sport ID

integer

country_id

Country of birth

integer

nationality_id

Nationality the driver represents

integer

city_id

City of birth

integer

position_id

Position within the team (first, second, or test driver)

integer

common_name

The name the driver is commonly known by

string

firstname

First name

string

lastname

Last name

string

name

Full name

string

display_name

Name recommended for display in applications

string

image_path

URL to the driver headshot

string

height

Height in centimetres

integer

weight

Weight in kilograms

integer

date_of_birth

Date of birth

string

gender

Gender

string

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:

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

Get a single driver by ID:

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

Search drivers by name:

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

Filter drivers by country:

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:

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:

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:

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

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,
  };
}

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"),
    }

<?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,
    ];
}

Search for a driver by name

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;
}

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"]

<?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"] ?? [];
}

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:

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]));
}

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}

<?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;
}

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

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.

Last updated 11 days ago

Was this helpful?

When to use this

Important: Driver and Player

The Driver entity fields

Available includes

Retrieving drivers

Driver metadata

Season-specific driver data

Working with the data

Common pitfalls

Common errors

See also

FAQ