1 of 1

Limiting

Sometimes you just want to limit your response a little bit!

In the previous tutorial, we have explained the fundamentals of filtering API responses, which allows you to request the exact data you need. However, sometimes the response can be rather large. In such cases, you can use our limiting feature. In this part of our tutorial, you will be able to limit your API responses.

What is limiting?

Limiting, as its name suggests, will limit the response you get from our API to a specific amount. Limiting your API responses can come in handy when you want to avoid big API responses. In this tutorial, we'll show you how limiting is used and why it may be handy for you. Let's go!

Create the request

In this tutorial, we will request all the fixtures from the 20/21 season from the Scottish Premiership (season id: 17141). As for the endpoint, we’ll go with season by id. Furthermore, as discussed in our includes tutorial, we’ll enrich the response with an include. In this case, we’ll use the include called fixtures

The below request will give you all the fixtures of the 20/21 season of the Scottish Premiership (season id: 17141).

The response is enormous. Therefore, we've copied a small snippet instead of the full response.

https://soccer.sportmonks.com/api/v2.0/seasons/17141?api_token={API_TOKEN}&include=fixtures

{
    "data": {
        "id": 17141,
        "name": "2020/2021",
        "league_id": 501,
        "is_current_season": true,
        "current_round_id": 194976,
        "current_stage_id": 77447501,
        "fixtures": {
            "data": [
                {
                    "id": 16475283,
                    "league_id": 501,
                    "season_id": 17141,
                    "stage_id": 77447501,
                    "round_id": 194968,
                    "group_id": null,
                    "aggregate_id": null,
                    "venue_id": 281425,
                    "referee_id": 15818,
                    "localteam_id": 496,
                    "visitorteam_id": 258,
                    "winner_team_id": 496,
                    "weather_report": {
                        "code": "clouds",
                        "type": "broken clouds",
                        "icon": "https://cdn.sportmonks.com/images/weather/04d.png",
                        "temperature": {
                            "temp": 60.62,
                            "unit": "fahrenheit"
                        },
                        "temperature_celcius": {
                            "temp": 15.9,
                            "unit": "celcius"
                        },
                        "clouds": "75%",
                        "humidity": "72%",
                        "pressure": 1013,
                        "wind": {
                            "speed": "5.82 m/s",
                            "degree": 300
                        },
                        "coordinates": {
                            "lat": 55.83,
                            "lon": -4.43
                        },
                        "updated_at": "2020-08-01T15:45:06.417645Z"
                    },
                    "commentaries": false,
                    "attendance": null,
                    "pitch": null,
                    "details": null,
                    "neutral_venue": false,
                    "winning_odds_calculated": true,
                    "formations": {
                        "localteam_formation": "4-2-3-1",
                        "visitorteam_formation": "3-4-2-1"
                    },
                    "scores": {
                        "localteam_score": 1,
                        "visitorteam_score": 0,
                        "localteam_pen_score": null,
                        "visitorteam_pen_score": null,
                        "ht_score": "1-0",
                        "ft_score": "1-0",
                        "et_score": null,
                        "ps_score": null
                    },
                    "time": {
                        "status": "FT",
                        "starting_at": {
                            "date_time": "2020-08-01 14:00:00",
                            "date": "2020-08-01",
                            "time": "14:00:00",
                            "timestamp": 1596290400,
                            "timezone": "UTC"
                        },
                        "minute": 90,
                        "second": null,
                        "added_time": null,
                        "extra_minute": null,
                        "injury_time": null
                    },
                    "coaches": {
                        "localteam_coach_id": 1621,
                        "visitorteam_coach_id": 22145896
                    },
                    "standings": {
                        "localteam_position": 3,
                        "visitorteam_position": 12
                    },
                    "assistants": {
                        "first_assistant_id": 12770,
                        "second_assistant_id": 36793,
                        "fourth_official_id": 19329
                    },
                    "leg": "1/1",
                    "colors": {
                        "localteam": {
                            "color": "#F0F0F0",
                            "kit_colors": "#F0F0F0,#F0F0F0,#0A0A0A,#0A0A0A,#0A0A0A,#FFDF1B,#F0F0F0"
                        },
                        "visitorteam": {
                            "color": "#FDBD0F",
                            "kit_colors": "#FDBD0F,#FDBD0F,#FAE403,#FAE403,#5C8FAE,#FFDF1B,#FDBD0F"
                        }
                    },
                    "deleted": false
                },

Season Field Description

Fixtures Field Description

Evaluate the response

Your first thought is probably: ‘Wow that’s an enormous response’. This is because football seasons tend to have a large number of matches. In order, to make the response more legible we can introduce a limit.

Limit the response

By limiting the response, we mean that you can limit the number of results per page. Let’s say we want to limit the response to only five results per page. You still need to use the fixtures include, but now you can add :limit(X|X).

The first attribute (X) is the number of records per page, while the second (X) is the page currently browsed.

For example, if you want 5 fixtures per page and you want to browse the first page: &include=fixtures:limit(5|1)

https://soccer.sportmonks.com/api/v2.0/seasons/17141?api_token={API_TOKEN}&include=fixtures:limit(5|1)

Now there are only five results per page! Moreover, you can simply replace the ‘1’ in (5|1) for a ‘2’, if you want to go to the second page. And just like that, you have successfully limited an API response!

Note that paginating through includes count towards your request limit

You’ve learnt how to filter and limit your response. Next up you will learn how to sort the API response.