Dataset Filtering, Sorting & Limiting

Dataset Filtering, Sorting & Limiting

Before you dive in to Filtering and limiting you must have a basic understanding of how the API works and what "including data" means. If these terms are unfamiliar for you, we suggest you to start reading Dataset Enrichment first.

{tip} Currently it's only possible to filter the first level of included data.

Imagine that we want to get the full season schedule of the 2018 English Premier League. We can request this data via the following URL.

https://soccer.sportmonks.com/api/v2.0/seasons/6397?api_token=__TOKEN__&include=fixtures

Filtering on parameters

At many endpoints you will have a few parameters available for filtering. With parameters you can add filters, by adding a comma separated list of ID's. Lets say you only want to show Fixtures on a certain date from the English Premier League and Championship.

https://soccer.sportmonks.com/api/v2.0/fixtures/date/2019-04-27?api_token=__TOKEN__&leagues=8,9

Filtering the includes

In some cases it might be useful to filter the includes to remove data you do not need. Let's say we have included flatOdds and only want the odds of bookmaker bet365.

https://soccer.sportmonks.com/api/v2.0/livescores/now?api_token=__TOKEN__&include=flatOdds:filter(bookmaker_id|2)

This will remove all the odds that are not from bet365 from the response so you don't have any overhead.

Sorting the includes

During the season games are being rescheduled due to, for example, FA cup games being played. Most of the time this will result in updated games, but since the game ids haven't changed, it can result in weird responses since we want it to be sorted based on starting_at attribute. Here include sorting comes in handy:

https://soccer.sportmonks.com/api/v2.0/seasons/6397?api_token=__TOKEN__&include=fixtures:order(starting_at|asc)

The above request will result in games sorted by starting_at attribute in ascending order.

limiting the includes

To prevent responses to become to big it might be useful to limit includes data and paginate through it. This can be easily done by limiting the response data

https://soccer.sportmonks.com/api/v2.0/seasons/6397?api_token=__TOKEN__&include=fixtures:limit(5|1)

The first attribute is the number of records per page while the second is the page currently browsed

{tip} Note that paginating through includes count towards your request limit.