Links

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.
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-02-17 10:19:55",
"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
},
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. 1.
    Add the parameter &filters=
  2. 2.
    Select the entity you want to filter on
  3. 3.
    Select the field you want to filter on
  4. 4.
    Fill in the ids you’re interested in.
In our case, this will result in the following steps:
  1. 1.
    Add the parameter &filters=
  2. 2.
    Select the entity you want to filter on: event
  3. 3.
    Select the field you want to filter on: Types (the event type substitution)
  4. 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-02-17 10:19:55",
"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_statistics_celtic_rangers.json
37KB
Code
The goal, substitutions and all statistics for Celtic vs Rangers
We’ve used the include statistics.type to have the name of the statistics type included in the response. More information about this can be found in our nested include tutorial.
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}
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_subs_goals_stats_ball_possession_celtic_rangers.json
9KB
Code
The goal, substitutions and all ball possession statistics for Celtic vs Rangers