Driver and Team Profile Guide

🏎️ Motorsport API Required
This guide requires an active Motorsport API subscription (€79/mo, 3,000 API calls/hr).
View pricing →

This guide walks through how to build driver and team profile pages using the Motorsport API - combining biographical data, current season context, championship standings, and race results into rich, data-driven profiles.

What you'll learn:

How to look up driver and team IDs by name
How to build a complete driver profile with biographical data, current team, and standings
How to build a complete team profile with constructor data, current drivers, and standings
How to enrich profiles with season race results

Prerequisites: Active Motorsport API subscription, API token, familiarity with REST APIs

1. When to use driver and team profiles

This approach is well suited to:

Driver profile pages showing career details, current team, championship position, and season results
Constructor profile pages showing team identity, current driver lineup, and championship standing
Fantasy F1 applications displaying driver cards with points and recent form
Comparison tools contrasting two drivers or constructors across a season

Profile data is relatively stable - driver biographical data rarely changes, and standings/results only update after each race weekend. Cache aggressively and refresh after race events.

2. Step 1: Look up the ID by name

Driver and team IDs are required for the standings and race results endpoints. Use the search endpoints to find them by name before making any other call.

Search for a driver:

GET /v3/motorsport/drivers/search/norris?api_token=YOUR_TOKEN

Search for a team:

GET /v3/motorsport/teams/search/mclaren?api_token=YOUR_TOKEN

Both search endpoints accept partial names and are case-insensitive. The id in the response is the value to use in all subsequent calls. For drivers, this is the same value referenced as player_id in race result lineups and participant_id in standings, laps, pitstops, and stints responses.

async function searchDriver(name, token) {
  const res = await fetch(
    `https://api.sportmonks.com/v3/motorsport/drivers/search/${encodeURIComponent(name)}?api_token=${token}`
  );
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const { data } = await res.json();
  return data[0] ?? null; // First result is typically the closest match
}

async function searchTeam(name, token) {
  const res = await fetch(
    `https://api.sportmonks.com/v3/motorsport/teams/search/${encodeURIComponent(name)}
?api_token=${token}`
  );
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const { data } = await res.json();
  return data[0] ?? null;
}

3. Step 2: Build a driver profile

With the driver ID in hand, fetch the full profile in a single enriched call:

GET /v3/motorsport/drivers/DRIVER_ID
?api_token=YOUR_TOKEN&include=teams.team;nationality;country;position;metadata

This returns:

Biographical data: full name, date of birth, headshot image
nationality - the country the driver represents
country - the driver's country of birth (may differ from nationality)
teams.team - the driver's current team with constructor name and logo
position - the driver's role within the team (first driver, second driver, or test driver)
metadata - additional profile data such as short name and debut information

Include depth on drivers is 3. teams.team counts as 2 levels (teams → team), leaving one further level available.

Key fields to use in your UI:

Field

Use for

display_name

Full name on profile header (e.g. "Max Verstappen")

common_name

Compact name for cards and leaderboards (e.g. "M. Verstappen")

image_path

Driver headshot image

date_of_birth

Age calculation and biography

nationality.name

Nationality flag and label

teams[0].team.name

Current constructor name

teams[0].team.image_path

Constructor logo

position.name

Team role (first driver, second driver)

4. Step 3: Get the driver's championship standing

With the driver's participant_id (same as their id) and the current season ID, fetch their championship position:

GET /v3/motorsport/standings/drivers/seasons/25273
?api_token=YOUR_TOKEN&include=participant;stage

This returns standings for all drivers. Filter client-side by participant_id to isolate the specific driver:

function getDriverStanding(standings, driverId) {
  return standings.find(s => s.participant_id === driverId) ?? null;
}

The stage include gives you the most recently completed race weekend - use stage.name and stage.sort_order to display "Championship position after Round X".

5. Step 4: Get the driver's season race results

Fetch the full season race result record for the driver using their ID and the season ID:

GET /v3/motorsport/results/seasons/25273/drivers/DRIVER_ID?api_token=YOUR_TOKEN

This returns all race and sprint race fixtures for the season with the driver's lineup and result details embedded. No includes are available - all data is pre-embedded.

Paginate through all pages to get the complete season. Use sort_order on each stage to order rounds chronologically. Extract position and points from the details array on each lineup object, resolving type_id values via the Results & Live Data Type Reference.

async function getDriverResults(seasonId, driverId, token) {
  const BASE = 'https://api.sportmonks.com/v3/motorsport';
  const results = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const res = await fetch(
      `${BASE}/results/seasons/${seasonId}/drivers/${driverId}?api_token=${token}&page=${page}`
    );
    if (!res.ok) throw new Error(`HTTP ${res.status}`);

    const payload = await res.json();
    results.push(...payload.data);

    hasMore = payload.pagination?.has_more ?? false;
    page++;
  }

  // Sort by calendar round and extract race fixtures only
  return results
    .sort((a, b) => a.sort_order - b.sort_order)
    .map(stage => {
      const raceFix = stage.fixtures?.find(f => f.name === 'Race');
      const lineup = raceFix?.lineups?.[0];
      const positionDetail = lineup?.details?.find(d => d.type_id === 9711);

      return {
        round: stage.sort_order,
        grand_prix: stage.name,
        fixture_id: raceFix?.id ?? null,
        grid_position: lineup?.grid_position ?? null,
        finish_position: positionDetail?.data?.position ?? null,
        driver_number: lineup?.driver_number ?? null
      };
    });
}

type_id: 9711 is the position result type confirmed from the live race results example (Norris P3 at Abu Dhabi). Verify all type IDs against the Results & Live Data Type Reference before deploying.

6. Building a team profile

Step 1: Fetch the team profile

GET /v3/motorsport/teams/TEAM_ID
?api_token=YOUR_TOKEN&include=drivers.driver;country;seasonDetails;seasonDrivers

This returns:

Team identity: name, short code, logo, founding year
country - the country the team is registered in
drivers.driver - current season driver lineup with full driver profiles
seasonDetails - per-season car details, team principal, and branding
seasonDrivers - driver participation details for the current season

Include depth on teams is 3. drivers.driver counts as 2 levels, leaving one further level.

Key fields for your UI:

Field

Use for

name

Team name on profile header (e.g. "McLaren")

short_code

Compact constructor code (e.g. "MCL")

image_path

Constructor logo

type

Power unit type (e.g. "hybrid")

drivers[].driver.display_name

Current driver names

drivers[].driver.image_path

Driver headshots

country.name

Constructor nationality

Step 2: Get the constructor championship standing

GET /v3/motorsport/standings/teams/seasons/25273
?api_token=YOUR_TOKEN&include=participant;stage

Filter by participant_id matching the team ID to isolate the specific constructor's standing. The points field contains the combined points of both drivers.

Step 3: Get the team's season race results

GET /v3/motorsport/results/seasons/25273/teams/TEAM_ID?api_token=YOUR_TOKEN

The team results response differs from the driver results response in one important way: the lineups array for each fixture contains both drivers who raced for that team. This means you can show both drivers' results side by side for each race weekend from a single call.

function extractTeamRaceResults(stages) {
  return stages
    .sort((a, b) => a.sort_order - b.sort_order)
    .map(stage => {
      const raceFix = stage.fixtures?.find(f => f.name === 'Race');

      const driverResults = (raceFix?.lineups ?? []).map(lineup => {
        const positionDetail = lineup.details?.find(d => d.type_id === 9711);
        return {
          driver_name: lineup.driver_name,
          driver_number: lineup.driver_number,
          grid_position: lineup.grid_position,
          finish_position: positionDetail?.data?.position ?? null,
          player_id: lineup.player_id
        };
      });

      return {
        round: stage.sort_order,
        grand_prix: stage.name,
        drivers: driverResults
      };
    });
}

7. Complete driver profile implementation

The following brings together all four steps for a driver profile page.

const BASE = 'https://api.sportmonks.com/v3/motorsport';
const TOKEN = 'YOUR_API_TOKEN';
const SEASON_ID = 25273;

async function buildDriverProfile(driverName) {
  // Step 1: find the driver
  const searchRes = await fetch(
    `${BASE}/drivers/search/${encodeURIComponent(driverName)}?api_token=${TOKEN}`
  );
  const { data: searchResults } = await searchRes.json();
  if (!searchResults.length) throw new Error('Driver not found');
  const driverId = searchResults[0].id;

  // Steps 2-4: fetch in parallel
  const [profileRes, standingsRes] = await Promise.all([
    fetch(`${BASE}/drivers/${driverId}?api_token=${TOKEN}&include=teams.team;nationality;position`),
    fetch(`${BASE}/standings/drivers/seasons/${SEASON_ID}?api_token=${TOKEN}&include=participant;stage`)
  ]);

  const { data: profile } = await profileRes.json();
  const { data: allStandings } = await standingsRes.json();

  const standing = allStandings.find(s => s.participant_id === driverId);
  const results = await getDriverResults(SEASON_ID, driverId, TOKEN);

  return {
    id: profile.id,
    name: profile.display_name,
    common_name: profile.common_name,
    image: profile.image_path,
    dob: profile.date_of_birth,
    nationality: profile.nationality?.name ?? null,
    team: profile.teams?.[0]?.team?.name ?? null,
    team_logo: profile.teams?.[0]?.team?.image_path ?? null,
    position: profile.position?.name ?? null,
    championship_position: standing?.position ?? null,
    championship_points: standing?.points ?? null,
    standings_as_of: standing?.stage?.name ?? null,
    race_results: results
  };
}

import requests

BASE = 'https://api.sportmonks.com/v3/motorsport'
TOKEN = 'YOUR_API_TOKEN'
SEASON_ID = 25273

def build_driver_profile(driver_name):
    # Step 1: find the driver
    search_res = requests.get(
        f'{BASE}/drivers/search/{driver_name}',
        params={'api_token': TOKEN},
        timeout=30
    )
    search_res.raise_for_status()
    search_results = search_res.json()['data']

    if not search_results:
        raise ValueError('Driver not found')

    driver_id = search_results[0]['id']

    # Step 2: fetch profile
    profile_res = requests.get(
        f'{BASE}/drivers/{driver_id}',
        params={
            'api_token': TOKEN,
            'include': 'teams.team;nationality;position'
        },
        timeout=30
    )
    profile_res.raise_for_status()
    profile = profile_res.json()['data']

    # Step 3: fetch standings
    standings_res = requests.get(
        f'{BASE}/standings/drivers/seasons/{SEASON_ID}',
        params={'api_token': TOKEN, 'include': 'participant;stage'},
        timeout=30
    )
    standings_res.raise_for_status()
    all_standings = standings_res.json()['data']
    standing = next(
        (s for s in all_standings if s['participant_id'] == driver_id),
        None
    )

    teams = profile.get('teams', [])
    current_team = teams[0].get('team') if teams else None

    return {
        'id': profile['id'],
        'name': profile['display_name'],
        'common_name': profile['common_name'],
        'image': profile['image_path'],
        'dob': profile['date_of_birth'],
        'nationality': profile.get('nationality', {}).get('name'),
        'team': current_team.get('name') if current_team else None,
        'team_logo': current_team.get('image_path') if current_team else None,
        'championship_position': standing['position'] if standing else None,
        'championship_points': standing['points'] if standing else None,
        'standings_as_of': standing.get('stage', {}).get('name') if standing else None
    }

8. Common pitfalls

Using name instead of display_name for UI display

The name field and display_name field often contain the same value but display_name is explicitly the field intended for application display. Use display_name for profile headers and common_name for compact timing-style displays.

Assuming teams[0] is always the current team

The teams include returns the driver's participation for the current season. In most cases this is a single entry, but always access it safely with optional chaining or a null check rather than assuming the array is populated.

Mixing up driver id and participant_id

The driver's id from the Drivers endpoint is the same value as player_id in race result lineups and participant_id in standings, laps, pitstops, and stints responses. These are three names for the same value. Always use the driver id as your cross-endpoint join key.

Fetching team results and expecting one driver per race

Unlike the driver results endpoint, the team results endpoint returns both drivers' lineups for each fixture. Your data processing must handle a lineups array with multiple entries per fixture, not just one.

Not paginating race results

Race results paginate at the stage level. A 24-round season will return results across multiple pages. Always paginate to get the complete season record.

Drivers - Driver endpoints and field reference
Teams - Team endpoints and field reference
Standings - Driver and constructor championship standings
Race Results - Season race result records
Season Dashboard Guide - Season-level data patterns
Results & Live Data Type Reference
Metadata & Per-Season Data Type Reference

10. FAQ

Q: How do I get a driver's age from date_of_birth?

date_of_birth is a YYYY-MM-DD string. Calculate age in your application by comparing it to the current date. Do not store a pre-calculated age value as it will become stale.

Q: The height and weight fields are null - is this expected?

Yes. These fields are present in the schema but sparsely populated. The search endpoint example shows height: 181 and weight: 72 for Verstappen, so data exists for some drivers. Always handle null gracefully in your application.

Q: How do I know which team a driver raced for in a past season?

The teams include returns current season participation. For historical team data, use the Race Results endpoint for that season - the team_id field in each lineup object shows which constructor the driver raced for in that specific race.

Q: Can I get a team's full historical driver roster across multiple seasons?

Use ?include=seasons on the team to get all seasons, then call the Race Results endpoint for each season using the team ID. The lineups array in each fixture shows all drivers who raced for that team.

Q: Is this available in all subscription plans?

All Motorsport API endpoints require an active Motorsport API subscription (€79/mo). View pricing →

Last updated 1 month ago

Was this helpful?