Filtering
In this tutorial, we'll explore how you can filter data requests to retrieve precisely the information you need. Filtering allows you to tailor your API calls to your specific requirements, making data retrieval more efficient and targeted.
Understanding Filtering Basics
Before we dive into filtering, let's understand the basics. Filtering in the Sportmonks API allows you to refine your requests based on specific criteria. There are two main types of filters:
Static Filters: These filters always operate in the same predefined way without any custom options.
Dynamic Filters: These filters are based on entities and includes, providing more flexibility in filtering options.
How-to use Static Filters
Static filters provide predefined filtering options that operate consistently across different endpoints. Unlike dynamic filters, which are based on entities, static filters have fixed functionality without customisation options. You can find all the Static Filters that you can use on a specific endpoint on the endpoint page by clicking the 'Static Filters' tab.
Please keep in mind that for a lot of the entities that don't have static filters, we do have a lot of dynamic filters available.
How you can use Dynamic Filters
Dynamic filters are entity-based, allowing you to specify the entity you wish to filter and apply criteria accordingly. Moreover, they can be combined with includes to refine data retrieval from related entities, enabling you to access detailed and specific data as per your filtering requirements. For example, the dynamic League filter is applicable across entities possessing a league_id field, such as fixtures and seasons.
So, how do you create a Dynamic Filter?
First you will need to define the base entity you want to filter on. This entity defines the starting point of your query and determines the context of your filtering. You can find this base entity by going through the 'Dynamic Filters' tab on the specific endpoint page or by using our Entities pages.
Please keep in mind that the base entity you want to filter on is always singular. So for example, if you want to filter fixtures the base entity would be fixture. The base entity also always start with a lower case later.
Once you've established the base entity, you specify the entities you expect to receive as a result of your filtering. These entities are related to the base entity and are the target of your filtering criteria.
Please keep in mind that the base entity that you expect to receive is always plural. So for example, if you filter on statistics and want to receive specific types you would useTypes in your request. The entity you'd like to receive always start with an upper case letter.
Finally, you specify the IDs you want to use for filtering within the selected entities. These IDs represent the specific criteria or attributes you're filtering on, such as specific types, states, teams, etc. You can provide either one or more IDs. You would need to separate them by commas (,) if you want to filter on multiple IDs. You can find all the IDs through our API. Some handy links are: Types, States and the ID finder.
Some examples
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:
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:
Add the parameter
&filters=Select the entity you want to filter on
Select the field you want to filter on
Fill in the ids you’re interested in.
In our case, this will result in the following steps:
Add the parameter
&filters=Select the entity you want to filter on:
eventSelect the field you want to filter on:
Types(the event type substitution)Fill in the ids you’re interested in:
18*
The type id of substitution is 18. You can request all types, and their id’s via the types endpoint.
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.
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:
Last updated
