How-to build a match page with line-ups/formations
In this guide, we'll show you how to correctly build a match page that shows the line-up/formation of the teams. This is one of our most frequently asked questions. So, we decided to create a how-to guide that will show you exactly how you can load the line-ups/formations. This guide will walk you step by step, from requesting the line-up data to putting players in their correct line-up grid.
You are going to need the following tools:
SportMonks API token
Postman (optional)
You can find a link to another article where we discuss the tools in-depth here.
There are various ways to get fixture IDs such as:
Use
fixturesinclude on the season by id endpointAnd many more
For this guide, we’ll go with the following fixture id: 16924631 (Manchester United - Tottenham Hotspur). This fixture id is also the default fixture id in our Postman collection.
Because we want the line-up from both teams we add the includes lineup and bench. Furthermore, it's interesting to know which players cannot play due to an injury or suspension. You can add the sidelined include for this as well. If you want the full name of players, please refer to Step 5.
A snippet of the response:
https://soccer.sportmonks.com/api/v2.0/fixtures/16924631?api_token={API_TOKEN}&include=lineup,bench,sidelined
"lineup": {"data": [{"team_id": 6,"fixture_id": 16924631,"player_id": 1014,"player_name": "Hugo Lloris","number": 1,"position": "G","additional_position": null,"formation_position": 1,"posx": 0,"posy": 0,"captain": true,"type": "lineup","stats": {"shots": {"shots_total": 0,"shots_on_goal": 0},"goals": {"scored": 0,"assists": 0,"conceded": 1,"owngoals": 0},"fouls": {"drawn": 0,"committed": 0},"cards": {"yellowcards": 0,"redcards": 0,"yellowredcards": 0},"passing": {"total_crosses": 0,"crosses_accuracy": 0,"passes": 17,"accurate_passes": 12,"passes_accuracy": 70,"key_passes": 0},"dribbles": {"attempts": 0,"success": 0,"dribbled_past": 0},"duels": {"total": 0,"won": 0},"other": {"aerials_won": 0,"punches": 0,"offsides": 0,"saves": 1,"inside_box_saves": 0,"pen_scored": 0,"pen_missed": 0,"pen_saved": 0,"pen_committed": 0,"pen_won": 0,"hit_woodwork": 0,"tackles": 0,"blocks": 0,"interceptions": 0,"clearances": 0,"dispossesed": 0,"minutes_played": 90},"rating": "6.42"}},{"team_id": 6,"fixture_id": 16924631,"player_id": 95094,"player_name": "Serge Aurier","number": 24,"position": "D","additional_position": null,"formation_position": 2,"posx": 0,"posy": 0,"captain": false,"type": "lineup","stats": {"shots": {"shots_total": 2,"shots_on_goal": 2},"goals": {"scored": 1,"assists": 1,"conceded": 0,"owngoals": 0},"fouls": {"drawn": 2,"committed": 0},"cards": {"yellowcards": 0,"redcards": 0,"yellowredcards": 0},"passing": {"total_crosses": 1,"crosses_accuracy": 0,"passes": 66,"accurate_passes": 56,"passes_accuracy": 84,"key_passes": 1},"dribbles": {"attempts": 1,"success": 1,"dribbled_past": 1},"duels": {"total": 11,"won": 7},"other": {"aerials_won": 0,"punches": 0,"offsides": 0,"saves": 0,"inside_box_saves": 0,"pen_scored": 0,"pen_missed": 0,"pen_saved": 0,"pen_committed": 0,"pen_won": 0,"hit_woodwork": 0,"tackles": 4,"blocks": 0,"interceptions": 2,"clearances": 3,"dispossesed": 1,"minutes_played": 90},"rating": "8.50"}},"bench": {"data": [{"team_id": 14,"fixture_id": 16924631,"player_id": 26031,"player_name": "Donny van de Beek","number": 34,"position": "M","additional_position": null,"formation_position": null,"posx": 0,"posy": 0,"captain": false,"type": "bench","stats": {"shots": {"shots_total": 0,"shots_on_goal": 0},"goals": {"scored": 0,"assists": 0,"conceded": 0,"owngoals": 0},"fouls": {"drawn": 0,"committed": 0},"cards": {"yellowcards": 0,"redcards": 0,"yellowredcards": 0},"passing": {"total_crosses": 0,"crosses_accuracy": 0,"passes": 11,"accurate_passes": 10,"passes_accuracy": 90,"key_passes": 0},"dribbles": {"attempts": 0,"success": 0,"dribbled_past": 0},"duels": {"total": 2,"won": 1},"other": {"aerials_won": 0,"punches": 0,"offsides": 0,"saves": 0,"inside_box_saves": 0,"pen_scored": 0,"pen_missed": 0,"pen_saved": 0,"pen_committed": 0,"pen_won": 0,"hit_woodwork": 0,"tackles": 1,"blocks": 0,"interceptions": 0,"clearances": 0,"dispossesed": 1,"minutes_played": 24},"rating": "6.60"}},{"team_id": 14,"fixture_id": 16924631,"player_id": 12647,"player_name": "Dean Henderson","number": 26,"position": "G","additional_position": null,"formation_position": null,"posx": null,"posy": null,"captain": null,"type": "bench","stats": {"shots": {"shots_total": null,"shots_on_goal": null},"goals": {"scored": 0,"assists": 0,"conceded": 0,"owngoals": 0},"fouls": {"drawn": null,"committed": null},"cards": {"yellowcards": 0,"redcards": 0,"yellowredcards": 0},"passing": {"total_crosses": null,"crosses_accuracy": null,"passes": null,"accurate_passes": null,"passes_accuracy": null,"key_passes": null},"dribbles": {"attempts": null,"success": null,"dribbled_past": null},"duels": {"total": null,"won": null},"other": {"aerials_won": null,"punches": null,"offsides": null,"saves": null,"inside_box_saves": null,"pen_scored": 0,"pen_missed": 0,"pen_saved": null,"pen_committed": null,"pen_won": null,"hit_woodwork": null,"tackles": null,"blocks": null,"interceptions": null,"clearances": null,"dispossesed": null,"minutes_played": null},"rating": null}},"sidelined": {"data": [{"team_id": 14,"fixture_id": 16924631,"player_id": 4391,"player_name": "A. Tuanzebe","reason": "Knock","position": "D"},{"team_id": 14,"fixture_id": 16924631,"player_id": 433,"player_name": "P. Jones","reason": "Knock","position": "D"},{"team_id": 6,"fixture_id": 16924631,"player_id": 251,"player_name": "G. Bale","reason": "Knee Injury","position": "A"},
Many of our users stop at this step, but some want to visually display the formation. In step 3 we’ll discuss how you can do that.
First, we want to know what formation, both teams used. Luckily, this information is included in the default response you get from our fixtures/livescores endpoints. For example:
"formations": {"localteam_formation": "4-2-3-1","visitorteam_formation": "4-3-3"
Before we fill in the formation, let me first explain formation positions.
In the example response from step 2, you could have noticed that the player's formation_position: 1. Our API slots formations from right to left, meaning that the visitorteam_formation will look like this for a classic 4-3-3 formation:
So, in this case, we have:
Formation Number | Outcome |
1 | Keeper |
2 | Right-back |
3 | Central defender |
4 | Central defender |
5 | Left-back |
6 | Right central midfielder |
7 | Central midfielder |
8 | Left central midfielder |
9 | Right-winger |
10 | Central forward |
11 | Left-winger |
Alright, back to filling in our formation. The visitor team used a 4-3-3 formation, while the visitor team used a 4-2-3-1 formation. So their respective formations will look like this:
1 (Goalkeeper) |
Formation_position: 1 (Hugo Lloris) |
4 (Defenders) |
Formation_position: 2 (Serge Aurier) |
Formation_position: 3 (Davinson Sánchez) |
Formation_position: 4 (Eric Dier) |
Formation_position: 5 (Sergio Reguilón) |
3 (Midfielders) |
Formation_position: 6 (Moussa Sissoko) |
Formation_position: 7 (Pierre-Emile Højbjerg) |
Formation_position: 8 (Tanguy Ndombélé) |
3 (Attackers) |
Formation_position: 9 (Érik Lamela) |
Formation_position: 10 (Harry Kane) |
Formation_position: 11 (Heung-Min Son) |
You can follow the same principle for the away team.
And that is how you can fill in the correct formation with our API. For any further questions, you can simply contact us by email at [email protected]
The API will return the name of the player with the first name as initial and last name written fully e.g. H. Kane, instead of Harry Kane.
In other cases, the player has a common name that isn’t the same as their actual full name. By using the nested include lineup.player, we can request all the player data we would need, including all their names.
https://soccer.sportmonks.com/api/v2.0/fixtures/16924631?api_token={API_TOKEN}&include=lineup.player
"player": {"data": {"player_id": 997,"team_id": 6,"country_id": 462,"position_id": 4,"common_name": "H. Kane","display_name": "Harry Kane","fullname": "Harry Kane","firstname": "Harry","lastname": "Kane","nationality": "England","birthdate": "28/07/1993","birthcountry": "England","birthplace": "London","height": "188 cm","weight": "86 kg","image_path": "https://cdn.sportmonks.com/images/soccer/players/5/997.png"}
We can see the various names and more specific player info of player Harrry Kane with this request.
This marks the end of this how-to guide. We hope you have gotten a better understanding of how our API sorts the line-ups and how you can put it in the right formation. See you in the next how-to guide!