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.
Step 1: Gather the tools 
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 on our Developer Tools Guide.​
Step 2: Get the fixture id for your match page
There are various ways to get fixture IDs such as:
​Fixtures by date (range)​
Use fixtures include on the season by id endpoint​
And 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:
Request
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.
Step 3: Know how formation positions work
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 us 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:

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
Step 4: Fill in the formation
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]​
Step 5: Advanced requests
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.
Request
Response
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!
How-to build a match page with events and statistics
How-to build a team page with season stats and squads
Last modified 1yr ago
Export as PDF
Copy link
Outline
Step 1: Gather the tools
Step 2: Get the fixture id for your match page
Step 3: Know how formation positions work
Step 4: Fill in the formation
Step 5: Advanced requests