OddsCoreAPI 2 (Deprecated)WidgetsContact

Lineups and formations

1.1 Requesting lineup and formation data

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:

https://api.sportmonks.com/v3/football/fixtures/19380879?api_token=YOURTOKEN&include=formations
Response
{
  "data": {
    "id": 19380879,
    "sport_id": 1,
    "league_id": 2,
    "season_id": 23619,
    "stage_id": 77471316,
    "group_id": null,
    "aggregate_id": 58589,
    "round_id": null,
    "state_id": 5,
    "venue_id": 151,
    "name": "Manchester City vs Real Madrid",
    "starting_at": "2025-02-11 20:00:00",
    "result_info": "Real Madrid won after full-time.",
    "leg": "1/2",
    "details": null,
    "length": 90,
    "placeholder": false,
    "has_odds": true,
    "has_premium_odds": true,
    "starting_at_timestamp": 1739304000,
    "formations": [
      {
        "id": 8405326,
        "fixture_id": 19380879,
        "participant_id": 3468,
        "formation": "4-4-2",
        "location": "away"
      },
      {
        "id": 8405325,
        "fixture_id": 19380879,
        "participant_id": 9,
        "formation": "4-1-4-1",
        "location": "home"
      }
    ]
  },

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:

  1. Formation position – The numerical placement of a player within the formation. (1-11)

  2. 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)

  3. 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.

PreviousFixturesNextStatistics

Last updated

Was this helpful?