> For the complete documentation index, see [llms.txt](https://docs.sportmonks.com/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/how-to-search-for-drivers-and-teams.md).

# 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 →](https://www.sportmonks.com/football-api/plans-pricing/)

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

```javascript
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:

```json
{
  "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:

```javascript
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

```javascript
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

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

Response fields:

```json
{
  "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

```javascript
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:

```javascript
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:

```javascript
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](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/drivers/get-drivers-by-search.md)
* [GET Teams by Search](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/teams/get-teams-by-search.md)

**Related entities**

* [Driver](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/driver.md)
* [Team](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/team.md)

**Related guides**

* [Driver and Team Profile Guide](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/driver-and-team-profile-guide.md)

### 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/how-to-search-for-drivers-and-teams.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.