How to Search for Drivers and Teams

✅ Included in All Plans

The search endpoints are included at no additional cost.

Plans differ only in leagues and API call limits.

Compare plans →

This guide shows you how to use the driver and team search endpoints to look up entities by name - useful for autocomplete inputs, driver ID resolution, and user-driven search features.

When to use this

Use the search endpoints when you want to:

• Build an autocomplete input that lets users find a driver or team by typing a name

• Resolve a driver or team name to an ID before calling standings or results endpoints

• Power a search feature in a fantasy F1 app or fan-facing dashboard

• Look up a driver or team without knowing their exact ID in advance

The two search endpoints

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

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

Both accept a partial name as the path parameter. The match is case-insensitive and matches against the full name. Both paginate - if your query returns many results, iterate through pages.

Driver search

Basic search

const API_TOKEN = 'your_token';

const response = await fetch(
  `https://api.sportmonks.com/v3/motorsport/drivers/search/Norris
?api_token=${API_TOKEN}`
);
const { data } = await response.json();
// data[0].id is the driver ID to use in standings, results, and laps endpoints

The response fields match the full Driver entity:

{
  "id": 37920802,
  "common_name": "L. Norris",
  "firstname": "Lando",
  "lastname": "Norris",
  "display_name": "Lando Norris",
  "image_path": "https://cdn.sportmonks.com/images/motorsport/players/...",
  "date_of_birth": "1999-11-13",
  "height": 163,
  "weight": 63
}

Use display_name for UI display and common_name for compact contexts like timing screens. The id is the value you pass to other endpoints as driver_id or that appears as participant_id in standings and player_id in lineups.

Search with enrichment

The driver search endpoint supports include depth 3 and the same include options as GET Driver by ID. You can enrich results with team, nationality, and position data in the same call:

const response = await fetch(
  `https://api.sportmonks.com/v3/motorsport/drivers/search/Hamilton
?api_token=${API_TOKEN}&include=teams.team;nationality`
);
const { data } = await response.json();

const driver = data[0];
console.log(driver.display_name);               // "Lewis Hamilton"
console.log(driver.nationality?.name);           // "British"
console.log(driver.teams?.[0]?.team?.name);      // "Ferrari"

Autocomplete pattern

async function searchDrivers(query, token) {
  if (query.length < 2) return []; // Avoid single-character queries

  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/drivers/search/${encodeURIComponent(query)}
?api_token=${token}&select=id,display_name,common_name,image_path`
  );
  const { data } = await response.json();
  return data;
}

// Wire to an input event with debounce
inputElement.addEventListener('input', debounce(async (e) => {
  const results = await searchDrivers(e.target.value, API_TOKEN);
  renderDropdown(results);
}, 300));

Using &select=id,display_name,common_name,image_path keeps the response tight for autocomplete - you only need the fields to display the suggestion and the ID to act on the selection.

Team search

Basic search

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

Response fields:

{
  "id": 276191,
  "name": "McLaren",
  "short_code": "MCL",
  "image_path": "https://cdn.sportmonks.com/images/motorsport/teams/...",
  "type": "hybrid",
  "founded": null,
  "last_played_at": "2025-05-17 14:46:00"
}

The id is the value to use in the team standings, team results, and venue search endpoints. short_code is the constructor's 3-letter abbreviation suitable for compact displays.

Search with driver lineup

const response = await fetch(
  `https://api.sportmonks.com/v3/motorsport/teams/search/Red Bull
?api_token=${API_TOKEN}&include=drivers`
);
const { data } = await response.json();

const team = data[0];
team.drivers?.forEach(d => {
  console.log(`Driver ID: ${d.player_id}`);
});

Partial name matching

Both search endpoints match on partial strings. Searching "Bull" returns both "Red Bull Racing" and "Visa Cash App RB" (which uses "Bull" in its registered name). Always handle multiple results and let the user select, rather than assuming data[0] is always the right match:

async function resolveTeam(query, token) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/teams/search/${encodeURIComponent(query)}
?api_token=${token}`
  );
  const { data } = await response.json();

  if (data.length === 1) return data[0]; // Unambiguous
  if (data.length === 0) return null;    // No match
  return data; // Return all for the user to choose
}

Common pitfalls

data[0] is not always the closest match. The API does not rank results by relevance. For common partial strings like "Red" or "Ham", multiple results may return in any order. Display all options and let the user select.

The search query is part of the URL path, not a query parameter. It is not ?search=Norris but /drivers/search/Norris. URL-encode the query string before placing it in the path - encodeURIComponent() in JavaScript handles this.

Driver IDs and team IDs are different namespaces. A driver ID (participant_id / player_id) is never the same value as a team ID. Do not interchange them across endpoints.

Short queries may return many results. Searching "a" returns every driver whose name contains "a". Add a minimum character check (2-3 characters) before firing the API call in autocomplete implementations.

The search endpoint paginate. If a query returns more results than the default page size, iterate through pages. For most real-world queries (a partial surname), this is unlikely to matter, but handle pagination defensively.

Advanced usage

To build a combined search that returns both drivers and teams, fire both search endpoints in parallel and merge the results client-side:

async function searchAll(query, token) {
  const [driversRes, teamsRes] = await Promise.all([
    fetch(`https://api.sportmonks.com/v3/motorsport/drivers/search/${encodeURIComponent(query)}?api_token=${token}`),
    fetch(`https://api.sportmonks.com/v3/motorsport/teams/search/${encodeURIComponent(query)}?api_token=${token}`)
  ]);

  const [{ data: drivers }, { data: teams }] = await Promise.all([
    driversRes.json(),
    teamsRes.json()
  ]);

  return {
    drivers: drivers.map(d => ({ type: 'driver', id: d.id, name: d.display_name, image: d.image_path })),
    teams: teams.map(t => ({ type: 'team', id: t.id, name: t.name, image: t.image_path }))
  };
}

Common errors

Status	Likely cause
401	Missing or invalid api_token
404	No results found for the query
422	Query complexity exceeded from includes - simplify the request

See also

Search endpoints

• GET Drivers by Search

• GET Teams by Search

Related entities

• Driver

• Team

Related guides

• Driver and Team Profile Guide

FAQ

Is the search case-sensitive? No. "norris", "Norris", and "NORRIS" return the same results.

Can I search by car number? No. The search endpoints match on name only. To look up a driver by car number, fetch all drivers for the season with GET Drivers by Season ID and filter client-side by driver_number from the lineup data.

Does the driver search include retired or historical drivers? Yes, within the seasons covered by the Motorsport API. The oldest available season is 2021 - the search is not scoped to the current season, so it may return drivers who competed in 2021 or later but are no longer on the grid. For example, searching "Schumacher" returns Mick Schumacher, who raced in F1 between 2021 and 2022. Filter by season using GET Drivers by Season ID if you only want current-season participants.