Use the entry’s player_id to join it to the player resource’s id. Keep the lineup entry’s own id separate. This applies to official lineup entries and predicted lineup entries; different selections do not require a name-based mapping.
For fixture 19722777, Callum McGregor is player_id: 8585 in both collections, and both nested player objects return id: 8585. The official entry is 14674899180 and the predicted entry is 366422.
GET https://api.sportmonks.com/v3/football/fixtures/19722777?api_token={{apiToken}}&include=lineups.player;predictedLineups.player
The include is written predictedLineups, while the checked response collection was named predictedlineups. Preserve the returned field casing in your parser. Handle missing relations and join by ID rather than display name or jersey number. For the player resource and season-statistic IDs, see the player-ID example.
Lineups connect to
Lineup data is most powerful when combined with other match information:
Player Statistics - Performance metrics for each player in the lineup
One of the most vital parts of a well-designed football application is displaying lineups and formations. To display lineups correctly, you need to retrieve data using the Sportmonks Football API. The key includes for fetching lineup and formation data are:
formations → Retrieves the formations of both teams.
lineups → Provides detailed player lineup data.
sidelined.sideline → Lists injured or suspended players.
1.1 Requesting formations
Each team starts their match in a specific formation. Formations dictate the positioning of players on the field and are essential for lineup visualisation. There are many formations available (e.g., 4-4-2, 4-3-3, 3-5-2). You can find every known formation in the definitions section.
To request formations, use the formations include in your API request:
Response
1.2 Requesting lineups
A lineup consists of the starting eleven players and their positions within the chosen formation. This information helps users display who is playing and where.
To request lineups, use the lineups include in your API request:
Response
1.3 Requesting detailed positions
Each player has a detailed position (e.g., Goalkeeper, Right-back, Central Midfield, Attacker). This is determined by the team’s formation and tactics.
To request detailed positions for players, use the nested include lineups.detailedposition:
Response
1.4 Combining the data
To properly display both team formations and player lineups, combine the formations and lineups includes in a single request:
Response
1.5 Filtering on starting 11 and bench
As you’ve probably noticed in the API response, the lineups include returns all the players. If you’re interested in only the starting eleven or only the benched players, you can use a filter based on the lineup type id. For example, if you’re interested in only the benched players:
Response
Or only the starting eleven:
Response
1.6 Sidelined players
A team may have players who are unavailable due to injuries or suspensions. This information is crucial for determining why certain players are missing from the lineup.
To retrieve sidelined players, use the sidelined.player include:
Response
Of course, you can combine all the information into one request:
Response
1.7 Predictive Line-ups
Another cool feature that has to do with the line-ups is predictive line-ups. In API 3.0, getting a line-up before the definitive line-up is released is now possible. When you use the “Fixture By ID” endpoint with the lineup include, you will see a line-up way before the actual line-up is released.
By using the include metadata, you can find the lineup_confirmed type. The type will be false if the club has yet to release the line-up. This is when we show a predicted line-up based on previous line-ups in games, suspended and injured players.
Response
Once the team/club officially releases their line-up, it will be set to true. Then the line-up we offer should reflect the final line-up as it is during the game.
Now, let's explain how you can display the lineups in a visual manner.
2. Displaying lineups in your football application
The lineup display in the application is based on a structured approach that ensures consistency across formations, formation positions, and detailed positions. The new processor streamlines the logic to eliminate discrepancies in the formation_field.
Rules of thumb:
The formation position and formation determine the detailed position and formation field.
The formation position is permanently assigned from bottom to top (for vertical formations) or right to left (for horizontal formations), relative to the home and away teams’ perspectives.
2.1 Formation Data Structure
Each team lineup consists of:
Formation position – The numerical placement of a player within the formation. (1-11)
Formation Field – The formation field provides a grid-based coordinate to visually position players on the field, making it easier to display them in a tactical formation view. (Formatted as line:line_position - like 2:4)
Detailed Position – The player's role based on their placement in the formation. (type ids)
2.2 Example Match: Manchester City vs. Real Madrid
Home Team: Manchester City
Formation: 4-1-4-1
Formation Positions & Mapping:
Player
Formation Position
Formation Field
Detailed Position
Ederson
1
1:1
Goalkeeper
Akanji
2
2:1
Right-back
Dias
3
2:2
Centre-back
Ake
4
2:3
Centre-back
Gvardiol
5
2:4
Left-back
Stones
6
3:1
Defensive Midfield
Savio
7
4:1
Right Midfield
De Bruyne
8
4:2
Central Midfield
Silva
9
4:3
Central Midfield
Grealish
10
4:4
Left Midfield
Haaland
11
5:1
Attacker
Away Team: Real Madrid
Formation: 4-4-2
Formation Positions & Mapping:
Player
Formation Position
Formation Field
Detailed Position
Courtois
1
1:1
Goalkeeper
Valverde
2
2:4
Right-back
Tchouameni
3
2:3
Centre-back
Asencio
4
2:2
Centre-back
Mendy
5
2:1
Left-back
Rodrygo
6
3:4
Right Midfield
Camavinga
7
3:3
Central Midfield
Ceballos
8
3:2
Central Midfield
Bellingham
9
3:1
Left Midfield
Mbappé
10
4:2
Attacker
Vinicius Jr.
11
4:1
Attacker
4. Summary
The formation position determines a player's numerical position within the formation.
The formation field provides a structured coordinate system for lineup display.
The detailed position assigns standard football roles based on formation positioning.
The new logic ensures consistency and accuracy in displaying formations across all teams.
