Nested includes

We ended the previous chapter with a small teaser about nested includes. Now in this part, we finally present to you the nested include. This tutorial will teach you what it is, where it is used and how you can apply them yourself.

Nested includes and relationships

Life is all about relationships. You are, for example, your parents’ child, your sister’s sibling, etc. Nested includes are no different from this because they too share a relationship with includes. The nested include allows you to further enrich your data, by requesting more information from a standard include. Might sound difficult, but we assure you, it’s anything but hard. Here’s how!

Create your request

For example, in our includes tutorial you’ve enriched your fixture by date request with the team and events includes:

https://soccer.sportmonks.com/api/v2.0/fixtures/date/2020-08-02?api_token={API_TOKEN}&include=localTeam,visitorTeam,events

The include event shows you the data about players who received a card, scored a goal, or were substituted. A snippet of the response:

Response
Field description
Response
"events": {
"data": [
{
"id": 16475287001,
"team_id": "338",
"type": "yellowcard",
"var_result": null,
"fixture_id": 16475287,
"player_id": 174161,
"player_name": "S. Martin",
"related_player_id": null,
"related_player_name": null,
"minute": 17,
"extra_minute": null,
"reason": null,
"injuried": null,
"result": null
},
{
"id": 16475287002,
"team_id": "53",
"type": "goal",
"var_result": null,
"fixture_id": 16475287,
"player_id": 96792,
"player_name": "O. Édouard",
"related_player_id": 173080,
"related_player_name": "G. Taylor",
"minute": 20,
"extra_minute": null,
"reason": null,
"injuried": null,
"result": "1-0"
},
{
"id": 16475287003,
"team_id": "53",
"type": "goal",
"var_result": null,
"fixture_id": 16475287,
"player_id": 8403182,
"player_name": "J. Frimpong",
"related_player_id": 173080,
"related_player_name": "G. Taylor",
"minute": 31,
"extra_minute": null,
"reason": null,
"injuried": null,
"result": "2-0"
},
{
"id": 16475287004,
"team_id": "338",
"type": "own-goal",
"var_result": null,
"fixture_id": 16475287,
"player_id": 32761,
"player_name": "C. Jullien",
"related_player_id": null,
"related_player_name": null,
"minute": 34,
"extra_minute": null,
"reason": null,
"injuried": null,
"result": "2-1"
},
}
Field description

Field

Description

id

The unique id of an event

team_id

The id of team the event belongs to

type

The event type. Possible values can be found in our statuses and definitions

var_result

The outcome of the Video Assistant Referee intervention. Possible values can be found in our statuses and definitions

fixture_id

The unique id of the fixture

player_id

The unique id of the main player involved in the event

player_name

The name of the main player involved in the event

related_player_id

The unique id of the second player involved in the event (if applicable)

related_player_name

The name of the second player involved in the event (if applicable)

minute

The minute of the fixture the event happened in

extra_minute

The extra minute of the fixture the event happened in (if applicable)

reason

The reason of the event. Mostly available when the event is a card. (if applicable)

injuried

Indicates if the event resulted in an injured player

results

The result of the event. Mostly available when the event is a goal. (if applicable)

But, what if we want to know more about these players, who scored a goal, like their country of origin, height, weight, age, image, etc. This is where the nested include comes into play!

Using nested includes

Because the include event is related to a player. You can add .playerto the include, which will result in the nested include: events.player

https://soccer.sportmonks.com/api/v2.0/fixtures/date/2020-08-02?api_token={API_TOKEN}&include=events.player
Response
Field description
Response
"events": {
"data": [
{
"id": 16475287001,
"team_id": "338",
"type": "yellowcard",
"var_result": null,
"fixture_id": 16475287,
"player_id": 174161,
"player_name": "S. Martin",
"related_player_id": null,
"related_player_name": null,
"minute": 17,
"extra_minute": null,
"reason": null,
"injuried": null,
"result": null,
"player": {
"data": {
"player_id": 174161,
"team_id": 338,
"country_id": 1161,
"position_id": 3,
"common_name": "S. Martin",
"display_name": "Scott Martin",
"fullname": "Scott Martin",
"firstname": "Scott",
"lastname": "Martin",
"nationality": "Scotland",
"birthdate": "01/04/1997",
"birthcountry": "Scotland",
"birthplace": "Glasgow",
"height": null,
"weight": null,
"image_path": "https://cdn.sportmonks.com/images/soccer/players/17/174161.png"
}
}
},
Field description

Field

Description

player_id

The unique id of the main player involved in the event

team_id

The unique id of the team the event belongs to

country_id

The unique id of the country the team plays in

position_id

The unique id of the position the player plays in

common_name

The common name the player is known for

display_name

The display name of the player. Often used to show in the lineup formation

fullname

The full name of the player

firstname

The first name of the player

lastname

The last name of the player

nationality

The nationality of the player

birthdate

The date of birth of the player

birthcountry

The country the player was born in

birthplace

The place the player was born in

height

The height of the player

weight

The weight of the player

image_path

The URL of the player image

The nested includes are represented in the form of dots (.), which are then linked to a standard include. This shows their relationship.

Now you've learnt how to enrich your response. In the next chapter you will learn how you can filter, sort and limit the response.