What are includes?

Includes are the cornerstone of our API and allow you to enrich and customise your requests. This flexibility is what distinguishes Sportmonks from all competitors.

This manner of flexibility lets you receive the specific data that interests you. Each endpoint comes with a list of includes.

You can see includes as something like an add-on to an endpoint. In this tutorial, we will show and explain what includes are and how you can make use of them. Don’t worry, though; using includes is relatively straightforward!

Creating the request

In this tutorial, our goal is to analyse a specific team. We want to know where the team is from, who is in the team and who the main goalscorers are.

Our starting endpoint will be get Team by {ID}.
(“GET”, “https://football-pro.p.rapidapi.com/api/v2.0/teams/{ID}”)

This request will give you all basic team information as you will see below.

Evaluating the response

All of our endpoints will give you a ‘basic’ response by default. As you can see, we will receive information mostly containing unique ids.

You can see the response below. You will find the ID of the team, the name, short code and a couple of other things.

{
“data”: {
“id”: 8,
“legacy_id”: 119,
“name”: “Liverpool”,
“short_code”: “LIV”,
“twitter”: “@LFC”,
“country_id”: 462,
“national_team”: false,
“founded”: 1892,
“logo_path”: “https://cdn.sportmonks.com/images/soccer/teams/8/8.png”,
“venue_id”: 230,
“current_season_id”: 21646,
“is_placeholder”: false
},

However, what if we want to know more about the players included in the squad, and what about the coach?

Enrich your response with includes

This is where includes come into play.
So, this was the base request:
(“GET”, “https://football-pro.p.rapidapi.com/api/v2.0/teams/{ID}”)

This next request will show you the extra data when using the right includes. In this case I will add the include coach. This way we will receive the whole squad of the specific team.

(“GET”, “https://football-pro.p.rapidapi.com/api/v2.0/teams/{ID}&include=coach”)

But we’re not done yet! We still want to know about the coach as well. Therefore, we add the include coach.
Another section is added and now we see the data of Jürgen Klopp.
“coach”: {
“data”: {
“coach_id”: 455353,
“team_id”: 8,
“country_id”: 11,
“common_name”: “J. Klopp”,
“fullname”: “Jürgen Klopp”,
“firstname”: “Jürgen”,
“lastname”: “Klopp”,
“nationality”: “Germany”,
“birthdate”: “16/06/1967”,
“birthcountry”: “Germany”,
“birthplace”: “Stuttgart”,

Like shooting fish in a barrel, right?

There is more

Our API has close to no limit on the number of includes per endpoint. This allows you to request all the extra data you want in the same request. So, we can simply add extra includes. As you can see, there is an extra part included in comparison to the basic response (keep in mind that in this example I only added one player below):

(“GET”, “https://football-pro.p.rapidapi.com/api/v2.0/teams/{ID}&include=coach,squad”)

“data”: [
[
“player_id”: 4125,
“position_id”: 4,
“number”: 11,
“captain”: 0,
“injured”: false,
“minutes”: 1384,
“appearences”: 16,
“lineups”: 16,
“substitute_in”: null,
“substitute_out”: 5,
“substitutes_on_bench”: null,
“goals”: 11,
“owngoals”: null,
“assists”: 7,
“saves”: null,
“inside_box_saves”: null,
“dispossesed”: 29,
“interceptions”: 2,
“yellowcards”: 1,
“yellowred”: null,
“redcards”: null,
“tackles”: 11,
“blocks”: 1,
“hit_post”: 1,
“cleansheets”: 5,
“rating”: “7.71”,
“fouls”: {
“committed”: 4,
“drawn”: 16
},
“crosses”: {
“total”: 19,
“accurate”: 4
},
“dribbles”: {
“attempts”: 43,
“success”: 14,
“dribbled_past”: 10
},
“duels”: {
“total”: 125,
“won”: 45
},
“passes”: {
“total”: 501,
“accuracy”: 77,
“key_passes”: 37
},
“penalties”: {
“won”: 1,
“scores”: 3,
“missed”: 1,
“committed”: null,
“saves”: null
},
“shots”: {
“shots_total”: 38,
“shots_on_target”: 21,
“shots_off_target”: null

Includes are basically add-ons that you can use with your request for additional information. The endpoint provides basic data, while the include gives you extra information.

Conclusion

Not all includes work with every endpoint. So please make sure that you check which includes are available per endpoint.