> 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-filter-drivers-by-country.md). # 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 →](https://www.sportmonks.com/football-api/plans-pricing/) 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 ```http 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: ```http 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 ```json { "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 ```javascript 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 ```javascript 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: ```javascript 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 | ### See also **Drivers endpoints** * [GET Drivers by Country ID](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/drivers/get-drivers-by-country-id.md) * [GET Drivers by Season ID](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/drivers/get-drivers-by-season-id.md) * [GET Drivers by Search](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/drivers/get-drivers-by-search.md) **Related entities** * [Driver](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/driver.md) **Related guides** * [How to Search for Drivers and Teams](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/how-to-search-for-drivers-and-teams.md) ### 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. --- # 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-filter-drivers-by-country.md?ask=&goal= ``` `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.