Teams

This guide covers how to retrieve constructor team data, enrich it with season-specific details, and use it to build team profiles, constructor cards, and driver rosters.

When to use this

Use the Teams endpoints when you want to:

Build a constructor team profile with logo, founding year, and country
Get the driver roster for a team in a specific season
Retrieve season-specific team details like chassis name, engine, and team colour
Search for a team by name

The Team entity fields

Field

Description

Type

id

Unique ID of the team

integer

sport_id

Sport ID

integer

country_id

Country of the team

integer

gender

Gender of the team

string

name

Full team name

string

short_code

Short code of the team

string

image_path

URL to the team logo

string

founded

Year the team was founded

integer

type

Team type

string

placeholder

Whether this is a placeholder team

boolean

last_played_at

Date and time of the team's last attended session

integer

venue_id is not used in the Motorsport API.

Available includes

sport country drivers latest upcoming seasons seasonDetails seasonDrivers

Retrieving teams

Get all teams in your subscription:

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

Get a single team by ID:

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

Search teams by name:

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

Filter teams by country:

GET https://api.sportmonks.com/v3/motorsport/teams
?api_token={your_token}&filters=teamCountries:{country_id}

Season-specific team data

The base team entity returns static information that does not change between seasons. Season-specific data - chassis name, engine, team colour, team lead, and the season name and logo the team used - is available via seasonDetails:

GET https://api.sportmonks.com/v3/motorsport/teams/{team_id}
?api_token={your_token}&include=seasonDetails

The confirmed seasonDetails types are:

Developer Name

Description

109854

ENGINE

Engine name

109855

CHASSIS

Chassis name

109856

TEAM_COLOR

Team colour as a hex code

109857

TEAM_LEAD

Team principal name

109858

TECHNICAL_LEAD

Technical director name

109861

TEAM_NAME

Name the team used during this season

109862

TEAM_IMAGE

Logo URL the team used during this season

110619

LEGACY_ID

The v1 team ID for migration purposes

Note that seasonDetails uses a different include name than metadata. Team season data is accessed via seasonDetails, not metadata.

Driver roster

To get the current driver roster for a team:

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

To get the driver roster for a specific season:

GET https://api.sportmonks.com/v3/motorsport/teams/{team_id}
?api_token={your_token}&include=seasonDrivers

drivers returns the current driver associations. seasonDrivers returns driver assignments per season, which is the right choice when building historical rosters or showing which drivers raced for the team in a given year.

Working with the data

Build a constructor team card

const API_TOKEN = 'your_token';

async function getTeamCard(teamId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/teams/${teamId}
     ?api_token=${API_TOKEN}&include=country;seasonDetails;drivers`
  );
  const { data: team } = await response.json();

  const seasonLookup = Object.fromEntries(
    (team.seasonDetails ?? []).map(s => [s.type_id, s.value])
  );

  return {
    name: team.name,
    shortCode: team.short_code,
    logo: team.image_path,
    country: team.country?.name ?? null,
    founded: team.founded,
    colour: seasonLookup[109856]?.color_code ?? null,
    chassis: seasonLookup[109855]?.chassis ?? null,
    engine: seasonLookup[109854]?.engine ?? null,
    teamLead: seasonLookup[109857]?.team_lead ?? null,
    drivers: (team.drivers ?? []).map(d => d.display_name),
  };
}

import requests

API_TOKEN = "your_token"

def get_team_card(team_id):
    url = f"https://api.sportmonks.com/v3/motorsport/teams/{team_id}"
    params = {
        "api_token": API_TOKEN,
        "include": "country;seasonDetails;drivers"
    }
    response = requests.get(url, params=params)
    team = response.json()["data"]

    season_lookup = {s["type_id"]: s["value"] for s in team.get("seasonDetails", [])}

    return {
        "name": team["name"],
        "short_code": team["short_code"],
        "logo": team["image_path"],
        "country": team["country"]["name"] if team.get("country") else None,
        "founded": team["founded"],
        "colour": season_lookup.get(109856, {}).get("color_code"),
        "chassis": season_lookup.get(109855, {}).get("chassis"),
        "engine": season_lookup.get(109854, {}).get("engine"),
        "team_lead": season_lookup.get(109857, {}).get("team_lead"),
        "drivers": [d["display_name"] for d in team.get("drivers", [])],
    }

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

    $seasonLookup = [];
    foreach ($team['seasonDetails'] ?? [] as $s) {
        $seasonLookup[$s['type_id']] = $s['value'];
    }

    return [
        'name' => $team['name'],
        'short_code' => $team['short_code'],
        'logo' => $team['image_path'],
        'country' => $team['country']['name'] ?? null,
        'founded' => $team['founded'],
        'colour' => $seasonLookup[109856]['color_code'] ?? null,
        'chassis' => $seasonLookup[109855]['chassis'] ?? null,
        'engine' => $seasonLookup[109854]['engine'] ?? null,
        'team_lead' => $seasonLookup[109857]['team_lead'] ?? null,
        'drivers' => array_map(fn($d) => $d['display_name'], $team['drivers'] ?? []),
    ];
}

Get the season-by-season roster for a team

async function getHistoricalRoster(teamId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/teams/${teamId}
     ?api_token=${API_TOKEN}&include=seasonDrivers`
  );
  const { data } = await response.json();
  return data.seasonDrivers ?? [];
}

def get_historical_roster(team_id):
    url = f"https://api.sportmonks.com/v3/motorsport/teams/{team_id}"
    params = {
        "api_token": API_TOKEN,
        "include": "seasonDrivers"
    }
    response = requests.get(url, params=params)
    team = response.json()["data"]
    return team.get("seasonDrivers", [])

<?php
const API_TOKEN = 'YOUR_TOKEN';
function get_historical_roster($teamId) {
    $url = "https://api.sportmonks.com/v3/motorsport/teams/" . $teamId;
    $params = [
        "api_token" => API_TOKEN,
        "include" => "seasonDrivers"
    ];
    $requestUrl = $url . "?" . http_build_query($params);
    $response = file_get_contents($requestUrl);
    if ($response === false) {
        return [];
    }
    $json = json_decode($response, true);
    $team = $json["data"] ?? [];
    return $team["seasonDrivers"] ?? [];
}

Search for a team

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

def search_team(name):
    url = f"https://api.sportmonks.com/v3/motorsport/teams/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_team($name) {
    $encodedName = urlencode($name);
    $url = "https://api.sportmonks.com/v3/motorsport/teams/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"] ?? [];
}

Common pitfalls

Using metadata to get season-specific team data. Team season data uses seasonDetails, not metadata. Using &include=metadata on a team request will not return chassis, engine, or colour data.

Treating name as the historical team name. Constructor teams often race under different names in different seasons (e.g. a team may rebrand between years). name is the current entity name. Use seasonDetails with TEAM_NAME (ID 109861) to get the name the team used in a specific season.

Using image_path for historical seasons. Similarly, image_path is the current logo. TEAM_IMAGE (ID 109862) in seasonDetails gives the logo the team used in a specific season.

venue_id is not used. This field exists for cross-sport compatibility and is always null in motorsport responses.

drivers returns current associations only. For season-by-season driver history, use seasonDrivers instead.

Common errors

Status

Likely cause

401

Missing or invalid api_token

404

The team ID does not exist or is not in your subscription

FAQ

How do I get the team colour for a UI element? Include seasonDetails and read the TEAM_COLOR type (ID 109856). The value object contains a color_code key with the hex colour string.

What is the difference between drivers and seasonDrivers? drivers returns the current driver assignments for the team. seasonDrivers returns driver assignments per season, including historical seasons. Use seasonDrivers for any feature that shows past driver-team relationships.

How do I get the engine and chassis name? Include seasonDetails and read ENGINE (ID 109854) and CHASSIS (ID 109855). These are season-specific and change year to year.

Why does the team logo look different from what I see on official sources? image_path returns the current team logo in the Sportmonks system. If you are building a historical feature, use TEAM_IMAGE (ID 109862) from seasonDetails to get the logo the team used in that specific season.

Can I get both drivers and season details in a single request? Yes. Separate multiple includes with a semicolon: &include=drivers;seasonDetails;country.

Last updated 11 days ago

Was this helpful?

When to use this

The Team entity fields

Available includes

Retrieving teams

Season-specific team data

Driver roster

Working with the data

Common pitfalls

Common errors

See also

FAQ