Dataset Enrichment

The flexibility of our API is in the part where you build your own responses by adding include parameters to your request. On every endpoint you can find information on what data can be included and how deep you can add includes. To best describe how to use includes and what the include limit means, we will give an explanation based on some example calls.

Getting Livescores

So, imagine you have an application that needs to show our fast livescores. To get all games currently played you will call the "Livescores In-play" endpoint like this:

https://soccer.sportmonks.com/api/v2.0/livescores/now?api_token=__TOKEN__

This will result in a collection of all games that are currently being played, and that are covered by your subscription.

Adding Team information

Usefull information for every game is home and away team information. How else would you know between which 2 teams the game is being played? Here we start with the interesting part, including team information.

https://soccer.sportmonks.com/api/v2.0/livescores/now?api_token=__TOKEN__&include=localTeam,visitorTeam

Note that we have extended our request with "&include=localTeam,visitorTeam". This results in information about the home and away team. You will retrieve a full team object related to the response whch includes the name, logo url and much more information.

Adding events and lineups

What is a game without the progression? Important information for your application to show could be events of goals, cards and substitutions but also the lineup.

https://soccer.sportmonks.com/api/v2.0/livescores/now?api_token=__TOKEN__&include=localTeam,visitorTeam,events,lineup

We have extended our request url with events and lineups now. Pretty cool right, but hey, to what players are the events related? With the current URL we have no clue since it only shows the player_id, not the actual name.

Adding nested includes

Luckely the flexibility of the API goes a step further with nested includes. Nested includes are basically relations on relations for the base endpoint. What?! relations of relations..... Imagine this: Lionel Messi has scored a goal in a game between Barcelona and Real Madrid. We already have the events loaded and we see that there is a node about it in the JSON:

{
    "id": 42973413,
    "team_id": "83",
    "type": "penalty",
    "fixture_id": 4194131,
    "player_id": 184798,
    "player_name": "L. Messi",
    "related_player_id": null,
    "related_player_name": null,
    "minute": 64,
    "extra_minute": null,
    "reason": null,
    "injuried": null,
    "result": "0-2"
}

Now, for most apps this is already more then enough info to show, but in this case we don't want the common name but the fullname we can enricht the event with actual player information showing all details of the player who was responsible for the event.

https://soccer.sportmonks.com/api/v2.0/livescores/now?api_token=__TOKEN__&include=localTeam,visitorTeam,events.player,lineup

Note we have added the .player to the event include?

{tip} You can add as many nested includes as described in the documentation section of the endpoint it self.

Include limit

The number of nested includes can be found on the documentation section of the endpoint. To make it more clear we will give you some examples. Imagine we have an include limit of 2.

https://soccer.sportmonks.com/api/v2.0/livescores/now?api_token=__TOKEN__&include=events.player

This will return all data requested.

https://soccer.sportmonks.com/api/v2.0/livescores/now?api_token=__TOKEN__&include=events.player.position

Since the includes are limited to 2 levels deep, the position part will not be rendered.

Wrapping Up

Based on the above examples you should be able to get a basic understanding of how the SportMonks API works. You can find all available includes on the documentation section of the endpoint itself. There, you can also find the limit of includes. To use nested includes you must check the documentation of a parent include as well.

Please also read the article about sorting and filtering since this will help you to perform more advanced logic.