Filtering

Filter your request
Filter on includes 
Next to selecting specific fields on the base entity or includes, it’s possible to filter your request.
Filters are improved in API 3 to give even more possibilities to get the data the way you need it. Each endpoint has two types of filters, static and dynamic filters. You can combine any dynamic filter with any static filter or use a multitude.
Static filters are always the same and filter in one specific way without any custom options. 
The dynamic filters are based on entities and includes. Each dynamic filter uses an entity to filter on and one entity to apply the filter to. Below is an example with an explanation of how filters are set up.
https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN&include=statistics&filters=statisticTypes:42,49
 
1.The include or base Entity you want to filter, this entity defines what you are filtering and what results are modified. In this case, you want to filter statistics. This is always a singular version of the entity.
2.The Entities you expect to receive when filtering. In this case, you want to receive all the statistics that have a specific type. This is always a plural version of the entity.
3.The ID's you want to filter on for the 2nd part, in this case types. You can separate the ID's by using a comma.
How about an example?
Let’s say you want to request all the events of a specific fixture, like Celtic vs Rangers. Your request would look like this:
https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=events
Response
{
  "data": {
    "id": 18535517,
    "sport_id": 1,
    "league_id": 501,
    "season_id": 19735,
    "stage_id": 77457866,
    "group_id": null,
    "aggregate_id": null,
    "round_id": 274719,
    "state_id": 5,
    "venue_id": 8909,
    "name": "Celtic vs Rangers",
    "starting_at": "2022-09-03 11:30:00",
    "result_info": "Celtic won after full-time.",
    "leg": "1/1",
    "details": null,
    "length": 90,
    "placeholder": false,
    "last_processed_at": "2023-03-02 17:47:38",
    "has_odds": true,
    "starting_at_timestamp": 1662204600,
    "events": [
      {
        "id": 42683644,
        "fixture_id": 18535517,
        "period_id": 4296154,
        "participant_id": 53,
        "type_id": 18,
        "section": "event",
        "player_id": 3298,
        "related_player_id": 10966261,
        "player_name": "Aaron Mooy",
        "related_player_name": "R. Hatate",
        "result": null,
        "info": null,
        "addition": null,
        "minute": 73,
        "extra_minute": null,
        "injured": false,
        "on_bench": false,
        "coach_id": null,
        "sub_type_id": null
      },
      {
        "id": 42683195,
        "fixture_id": 18535517,
        "period_id": 4296154,
        "participant_id": 53,
        "type_id": 18,
        "section": "event",
        "player_id": 319282,
        "related_player_id": 9939171,
        "player_name": "Daizen Maeda",
        "related_player_name": "L. Abada",
        "result": null,
        "info": null,
        "addition": null,
        "minute": 73,
        "extra_minute": null,
        "injured": false,
        "on_bench": false,
        "coach_id": null,
        "sub_type_id": null
      },
      {
        "id": 42703418,
        "fixture_id": 18535517,
        "period_id": 4296154,
        "participant_id": 62,
        "type_id": 19,
        "section": "event",
        "player_id": 2927,
        "related_player_id": null,
        "player_name": "Connor Goldson",
        "related_player_name": null,
        "result": null,
        "info": "Foul",
        "addition": "6th Yellow Card",
        "minute": 90,
        "extra_minute": null,
        "injured": null,
        "on_bench": false,
        "coach_id": null,
        "sub_type_id": null
      },
      // And more
As you can see in the response, you will receive all match events. But what if you’re only interested in a specific event like goals, cards or substitutions? You can filter on the specific data you're interested in.
For this example, we are only interested in the substitutions.
To filter your request, you need to:
1.Add the parameter &filters= 
2.Select the entity you want to filter on 
3.Select the field you want to filter on 
4.Fill in the IDs you’re interested in.
In our case, this will result in the following steps:
1.Add the parameter &filters= 
2.Select the entity you want to filter on: event 
3.Select the field you want to filter on: Types (the event type substitution) 
4.Fill in the IDs you’re interested in: 18 *
https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=events&filters=eventTypes:18
Response
{
  "data": {
    "id": 18535517,
    "sport_id": 1,
    "league_id": 501,
    "season_id": 19735,
    "stage_id": 77457866,
    "group_id": null,
    "aggregate_id": null,
    "round_id": 274719,
    "state_id": 5,
    "venue_id": 8909,
    "name": "Celtic vs Rangers",
    "starting_at": "2022-09-03 11:30:00",
    "result_info": "Celtic won after full-time.",
    "leg": "1/1",
    "details": null,
    "length": 90,
    "placeholder": false,
    "last_processed_at": "2023-03-02 17:47:38",
    "has_odds": true,
    "starting_at_timestamp": 1662204600,
    "events": [
      {
        "id": 42683644,
        "fixture_id": 18535517,
        "period_id": 4296154,
        "participant_id": 53,
        "type_id": 18,
        "section": "event",
        "player_id": 3298,
        "related_player_id": 10966261,
        "player_name": "Aaron Mooy",
        "related_player_name": "R. Hatate",
        "result": null,
        "info": null,
        "addition": null,
        "minute": 73,
        "extra_minute": null,
        "injured": false,
        "on_bench": false,
        "coach_id": null,
        "sub_type_id": null
      },
      {
        "id": 42683195,
        "fixture_id": 18535517,
        "period_id": 4296154,
        "participant_id": 53,
        "type_id": 18,
        "section": "event",
        "player_id": 319282,
        "related_player_id": 9939171,
        "player_name": "Daizen Maeda",
        "related_player_name": "L. Abada",
        "result": null,
        "info": null,
        "addition": null,
        "minute": 73,
        "extra_minute": null,
        "injured": false,
        "on_bench": false,
        "coach_id": null,
        "sub_type_id": null
      },
The type ID of substitution is 18. You can request all types, and their id’s via the types endpoint: 
https://api.sportmonks.com/v3/core/types?api_token=YOUR_TOKEN
“What if I want to have multiple types of events?” 
Great question: simply add another ID to your request. For example, goals (id: 14): 
https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=events&filters=eventTypes:18,14
​
It might be useful to check our syntax section to help you build your request.
Filter on multiple includes 
You can also filter on multiple includes. Let’s say you want the goals, substitutions, and the match's statistics. As you’ve learnt in the above example, you can filter the events via the &filters=eventTypes: parameter.
https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=events;statistics.type&filters=eventTypes:18,14
events_subs_stats_celtic_rangers.json
37KB
Code
The goal, substitutions and all statistics for Celtic vs Rangers
Including .type is not recommended as an include on any endpoint. Types are used throughout the entire API. We recommend retrieving all types from the types endpoint and storing them in your database or other data structure. Only include the type if no other option is available or when testing the API.
It's important to note that statistics can be retrieved from multiple entities. Therefore you also need to specify for which entity you want to filter the statistics. You can do this by prefixing the filter with the entity's name.
Common used filters are: 
Fixtures: fixtureStatisticTypes:{ids} 
Players: playerStatisticTypes:{ids} 
Teams: teamStatisticsTypes:{ids} 
Season: seasonStatisticsTypes:{ids} 
Lineups: lineupDetailTypes:{ids} 
Team statistics for one season: teamStatisticSeasons:{season_ids} 
Player statistics for one season: playerStatisticSeasons:{season_ids}
It is now possible to add the filters=populate to your query parameter. This parameter allows for a higher pagination limit (max 1000), so you can populate your database in a more convenient way instead of using the default pagination limit of 50. To prevent our services from being overloaded, using includes is disabled when this filter is added to the request.
Now, we’re only interested in the ball possession statistics. As you can see in the response or via the types endpoint, the ID of ball possession is 45. 
With this information, we can build the request. We know we want the statistics on the fixtures entity for a certain type: fixtureStatisticTypes:45 This results in the below request:
https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=events;statistics.type&filters=eventTypes:18,14;fixtureStatisticTypes:45
events_sub_goals_stats_ball_poss_celtic_rangers.json
9KB
Code
The goal, substitutions and all ball possession statistics for Celtic vs Rangers
​
Selecting fields
Selecting and filtering
Last modified 17d ago