Filtering

This guide covers how to use &filters= to narrow down which records the API returns, and how static and dynamic filters differ.

The basics

Filtering controls which records come back, not which fields are on each record. For field-level control, see Selecting fields.

There are two kinds of filters:

Static filters are predefined and filter in one fixed way with no custom options. Not every endpoint has static filters.

Dynamic filters are entity-based. You name the entity you want to filter on and pass one or more IDs as the value:

GET https://api.sportmonks.com/v3/motorsport/fixtures
?api_token={your_token}&filters=fixtureLeagues:3468

fixtureLeagues is the filter name and 3468 is the league ID to filter on. Pass multiple values as a comma-separated list:

GET https://api.sportmonks.com/v3/motorsport/fixtures
?api_token={your_token}&filters=fixtureLeagues:3468,3470

The general &filters= syntax is documented on Request options.

Available filters by entity

You can retrieve the full filter catalogue for your subscription at any time by calling:

GET https://api.sportmonks.com/v3/my/filters/entity?api_token={your_token}

The motorsport entities and their confirmed dynamic filters are listed below.

Fixtures

Filter

Filters by

fixtureLeagues

League ID

fixtureSeasons

Season ID

fixtureStates

State ID

fixtureStages

Stage ID

venues

Venue ID

todaydate

Today's fixtures only

deleted

Soft-deleted fixtures

participantsearch

Driver or team name (string search)

Drivers (driver is an alias for the player entity, so player filters apply)

Filter

Filters by

playerCountries

Country ID

genders

Gender

Teams

Filter

Filters by

teamCountries

Country ID

genders

Gender

Laps

Filter

Filters by

lapLeagues

League ID

Lap details

Filter

Filters by

lapdetailLeagues

League ID

lapdetailTypes

Type ID

Pitstops

Filter

Filters by

pitstopLeagues

League ID

Pitstop details

Filter

Filters by

pitstopdetailLeagues

League ID

pitstopdetailTypes

Type ID

Stints

Filter

Filters by

stintLeagues

League ID

Stint details

Filter

Filters by

stintdetailLeagues

League ID

stintdetailTypes

Type ID

Standings

Filter

Filters by

standingLeagues

League ID

standingSeasons

Season ID

standingGroups

Group ID

standingStages

Stage ID

Seasons

Filter

Filters by

seasonLeagues

League ID

Leagues

Filter

Filters by

leagueLeagues

League ID

leagueCountries

Country ID

Stages

Filter

Filters by

stageLeagues

League ID

stageSeasons

Season ID

stageTypes

Type ID

stageStages

Stage ID

Lineups

Filter

Filters by

lineupLeagues

League ID

lineupTypes

Type ID

lineupPlayers

Driver ID

Lineup details

Filter

Filters by

lineupdetailLeagues

League ID

lineupdetailTypes

Type ID

lineupdetailPlayers

Driver ID

Metadata

Filter

Filters by

metadataTypes

Type ID

Working with the data

Filter fixtures by season

const API_TOKEN = 'your_token';

async function getFixturesBySeason(seasonId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/fixtures?api_token=${API_TOKEN}&filters=fixtureSeasons:${seasonId}`
  );
  const { data } = await response.json();
  return data;
}

import requests

API_TOKEN = "your_token"

def get_fixtures_by_season(season_id):
    url = "https://api.sportmonks.com/v3/motorsport/fixtures"
    params = {
        "api_token": API_TOKEN,
        "filters": f"fixtureSeasons:{season_id}"
    }
    response = requests.get(url, params=params)
    return response.json()["data"]

<?php
function getFixturesBySeason(string $apiToken, int $seasonId): array {
    $url = "https://api.sportmonks.com/v3/motorsport/fixtures?api_token={$apiToken}&filters=fixtureSeasons:{$seasonId}";
    $response = json_decode(file_get_contents($url), true);
    return $response['data'];
}

Filter drivers by country

async function getDriversByCountry(countryId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/drivers?api_token=${API_TOKEN}&filters=playerCountries:${countryId}`
  );
  const { data } = await response.json();
  return data;
}

def get_drivers_by_country(country_id):
    url = "https://api.sportmonks.com/v3/motorsport/drivers"
    params = {
        "api_token": API_TOKEN,
        "filters": f"playerCountries:{country_id}"
    }
    response = requests.get(url, params=params)
    return response.json()["data"]

<?php
function getDriversByCountry(string $apiToken, int $countryId): array {
    $url = "https://api.sportmonks.com/v3/motorsport/drivers?api_token={$apiToken}&filters=playerCountries:{$countryId}";
    $response = json_decode(file_get_contents($url), true);
    return $response['data'];
}

Filter standings by season

async function getStandingsBySeason(seasonId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/standings?api_token=${API_TOKEN}&filters=standingSeasons:${seasonId}`
  );
  const { data } = await response.json();
  return data;
}

def get_standings_by_season(season_id):
    url = "https://api.sportmonks.com/v3/motorsport/standings"
    params = {
        "api_token": API_TOKEN,
        "filters": f"standingSeasons:{season_id}"
    }
    response = requests.get(url, params=params)
    return response.json()["data"]

<?php
function getStandingsBySeason(string $apiToken, int $seasonId): array {
    $url = "https://api.sportmonks.com/v3/motorsport/standings?api_token={$apiToken}&filters=standingSeasons:{$seasonId}";
    $response = json_decode(file_get_contents($url), true);
    return $response['data'];
}

Combining filters with field selection

Filtering and field selection are independent and can be used together:

GET https://api.sportmonks.com/v3/motorsport/fixtures
?api_token={your_token}
&filters=fixtureSeasons:25273
&select=name,starting_at

Common pitfalls

Using a driver filter name that doesn't exist. Driver is an alias for the player entity in the Sportmonks data model, so driver filters use the player prefix: playerCountries, not driverCountries.

Forgetting the colon syntax. Dynamic filters use filterName:value inside the filters parameter. The outer parameter is &filters=; the colon separates the filter name from its value.

Passing multiple values with a semicolon instead of a comma. Multiple values for the same filter are comma-separated: fixtureLeagues:3468,3470. Semicolons are for separating multiple includes in &include=, not multiple filter values.

Assuming every filter works on every endpoint. fixtureLeagues only works on fixture-related endpoints. lapLeagues only works on lap endpoints. Check the table above and confirm against the endpoint's own documentation before building a request around a specific filter.

FAQ

How do I find all available filters for my subscription? Call GET https://api.sportmonks.com/v3/my/filters/entity?api_token={your_token}. This returns the full filter catalogue for every entity your subscription has access to.

Why does filtering drivers use playerCountries instead of driverCountries? Driver is an alias for the player entity in the Sportmonks data model. The underlying entity is player, so its filters use the player prefix. The same filter names used for football players apply to motorsport drivers.

Can I stack multiple different filters in one request? Yes. Separate them with a semicolon inside the &filters= value: &filters=fixtureSeasons:25273;fixtureStates:5. Each filter narrows the result set further.

What is deleted used for on fixtures? The deleted filter returns soft-deleted fixtures. This is useful for database sync workflows where you need to track fixtures that have been removed. See How to keep your race data in sync for the full sync pattern.

Last updated 11 days ago

Was this helpful?

The basics

Available filters by entity

Working with the data

Common pitfalls

See also

FAQ