For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 a single driver by ID:

Search drivers by name:

Filter drivers by country:

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:

Season-specific driver data

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

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

Search for a driver by name

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:

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

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.

Last updated

Was this helpful?