How to Filter Drivers by Country

✅ Included in All Plans
The drivers by country endpoint is included at no additional cost.
Plans differ only in leagues and API call limits.
Compare plans →

This guide shows you how to retrieve all drivers associated with a specific country using the GET Drivers by Country ID endpoint.

When to use this

Use this endpoint when you want to:

Build a national fan feature showing all drivers from a specific country
Filter the driver roster by country of birth or nationality for a regional app
Populate a country-based driver picker in a fantasy or prediction product

Country ID vs Nationality ID

The Driver entity has two country-related fields:

Field

Meaning

country_id

The country where the driver was born

nationality_id

The nationality the driver has chosen to represent

These are not always the same. A driver born in one country may hold citizenship in and race under another. The GET Drivers by Country ID endpoint filters on country_id (country of birth). To filter by nationality instead, fetch all drivers for a season with GET Drivers by Season ID and filter client-side on nationality_id.

How to retrieve the data

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

You need the Sportmonks country ID, not a country code or name. Use the core countries endpoint to look up country IDs:

GET https://api.sportmonks.com/v3/core/countries
?api_token={your_token}

The response includes id, name, iso2, and iso3 fields for each country.

Example response

{
  "data": [
    {
      "id": 37920800,
      "country_id": 38,
      "nationality_id": 38,
      "common_name": "M. Verstappen",
      "display_name": "Max Verstappen",
      "image_path": "https://cdn.sportmonks.com/images/motorsport/players/0/37920800.png",
      "date_of_birth": "1997-09-30",
      "height": 181,
      "weight": 72
    }
  ]
}

Country ID 38 is the Netherlands in the Sportmonks system. The id on each driver is their driver ID, which matches participant_id in standings responses and player_id in lineup responses.

Working with the data

Fetch all drivers from a country

const API_TOKEN = 'your_token';
const NETHERLANDS_ID = 38;

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

drivers.forEach(driver => {
  console.log(`${driver.display_name} (born: ${driver.date_of_birth})`);
});

Resolve a country name to an ID first

async function getCountryId(countryName, token) {
  let page = 1;
  while (true) {
    const res = await fetch(
      `https://api.sportmonks.com/v3/core/countries?api_token=${token}&page=${page}`
    );
    const { data, pagination } = await res.json();

    const match = data.find(c =>
      c.name.toLowerCase() === countryName.toLowerCase()
    );
    if (match) return match.id;
    if (!pagination.has_more) return null;
    page++;
  }
}

const britainId = await getCountryId('United Kingdom', API_TOKEN);
const response = await fetch(
  `https://api.sportmonks.com/v3/motorsport/drivers/countries/${britainId}
?api_token=${API_TOKEN}&include=teams`
);

Enrich with current team

The endpoint supports include depth 3 and the full driver include options. Add teams to get the driver's current team:

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

drivers.forEach(driver => {
  const teamName = driver.teams?.[0]?.team?.name ?? 'No current team';
  console.log(`${driver.display_name} - ${teamName}`);
});

Common pitfalls

country_id is country of birth, not nationality. Carlos Sainz was born in Spain but raced under a Spanish licence - these happen to match. But not all drivers' country_id and nationality_id are the same. If your use case is about which flag a driver races under, filter on nationality_id instead using GET Drivers by Season ID client-side.

You need the Sportmonks country ID, not ISO codes. The endpoint path takes a numeric ID. Use the core countries endpoint to find IDs. Alternatively, the country include on a driver entity returns the country object including its id.

The endpoint returns all historical drivers, not just current-season participants. If you want only drivers who raced in the current season, cross-reference the results with GET Drivers by Season ID.

The endpoint paginates. For countries with many historical drivers, iterate through pages.

Common errors

Status

Likely cause

401

Missing or invalid api_token

404

The country_id does not exist

FAQ

How do I find the country ID for a specific country? Call GET https://api.sportmonks.com/v3/core/countries?api_token={your_token} and search for the country by name, iso2, or iso3. The id field is the value to use.

Can I filter by nationality rather than country of birth? The endpoint filters on country of birth (country_id). To filter by nationality, fetch all drivers for a season with GET Drivers by Season ID and filter the response client-side on nationality_id.

Does this return test or reserve drivers? Yes, if they have a country_id matching the requested country. Filter by position_id if you want to limit to first or second drivers only - see the Results and Live Data Type Reference for the position type IDs.

Last updated 1 month ago

Was this helpful?