Lineups and formations

One of the most vital parts of a well-designed football application is displaying lineups and formations.

You can use the formations include to obtain the formations of the participants:

Example request

​​https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=
formations

Example response

{
  "data": {
    "id": 18804545,
    "sport_id": 1,
    "league_id": 2286,
    "season_id": 19724,
    "stage_id": 77457819,
    "group_id": null,
    "aggregate_id": null,
    "round_id": null,
    "state_id": 5,
    "venue_id": 5530,
    "name": "Fiorentina vs West Ham United",
    "starting_at": "2023-06-07 19:00:00",
    "result_info": "West Ham United won after full-time.",
    "leg": "1/1",
    "details": null,
    "length": 90,
    "placeholder": false,
    "has_odds": true,
    "starting_at_timestamp": 1686164400,
    "formations": [
      {
        "id": 426436,
        "fixture_id": 18804545,
        "participant_id": 1,
        "formation": "4-2-3-1",
        "location": "away"
      },
      {
        "id": 426437,
        "fixture_id": 18804545,
        "participant_id": 109,
        "formation": "4-2-1-3",
        "location": "home"
      }
    ]
  },

It’s great to combine this with the lineups include:

Example request

​​https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=
formations;lineups

Example response

{
  "data": {
    "id": 18804545,
    "sport_id": 1,
    "league_id": 2286,
    "season_id": 19724,
    "stage_id": 77457819,
    "group_id": null,
    "aggregate_id": null,
    "round_id": null,
    "state_id": 5,
    "venue_id": 5530,
    "name": "Fiorentina vs West Ham United",
    "starting_at": "2023-06-07 19:00:00",
    "result_info": "West Ham United won after full-time.",
    "leg": "1/1",
    "details": null,
    "length": 90,
    "placeholder": false,
    "has_odds": true,
    "starting_at_timestamp": 1686164400,
    "formations": [
      {
        "id": 426436,
        "fixture_id": 18804545,
        "participant_id": 1,
        "formation": "4-2-3-1",
        "location": "away"
      },
      {
        "id": 426437,
        "fixture_id": 18804545,
        "participant_id": 109,
        "formation": "4-2-1-3",
        "location": "home"
      }
    ],
    "lineups": [
      {
        "id": 3506941917,
        "sport_id": 1,
        "fixture_id": 18804545,
        "player_id": 733,
        "team_id": 1,
        "position_id": 24,
        "formation_field": null,
        "type_id": 12,
        "formation_position": null,
        "player_name": "Lukasz Fabianski",
        "jersey_number": 1
      },
      {
        "id": 3506941811,
        "sport_id": 1,
        "fixture_id": 18804545,
        "player_id": 581199,
        "team_id": 1,
        "position_id": 25,
        "formation_field": null,
        "type_id": 12,
        "formation_position": null,
        "player_name": "B. Johnson",
        "jersey_number": 2
      },
      {
        "id": 3481455350,
        "sport_id": 1,
        "fixture_id": 18804545,
        "player_id": 1261,
        "team_id": 1,
        "position_id": 25,
        "formation_field": null,
        "type_id": 12,
        "formation_position": 5,
        "player_name": "Aaron Cresswell ",
        "jersey_number": 3
      },
      {
        "id": 3481455351,
        "sport_id": 1,
        "fixture_id": 18804545,
        "player_id": 1316,
        "team_id": 1,
        "position_id": 25,
        "formation_field": "2:2",
        "type_id": 11,
        "formation_position": 3,
        "player_name": "Kurt Zouma",
        "jersey_number": 4
      },
      {
        "id": 3506941929,
        "sport_id": 1,
        "fixture_id": 18804545,
        "player_id": 80304,
        "team_id": 1,
        "position_id": 25,
        "formation_field": "2:1",
        "type_id": 11,
        "formation_position": 2,
        "player_name": "Vladimir Coufal",
        "jersey_number": 5
      },
 //and more

Bench and sidelined

You can find all bench players as well. You need to use lineupType:12 to receive these players.

Another great feature is to find all sidelined players. When using the include sidelined.sideline you will receive all players with suspensions and injuries.

Creating the Lineup

Before we fill in the formation, let us first explain formation positions. Players have different formation_positions. So for example, one player has the player’s formation_position: 1, another has formation_position: 2, etc. Our API slots formations from right to left, meaning that the visitorteam_formation will look like the one down below.

You can use the formation numbers in combination with the lineup formation to display formations. The formation number is by order of the lineup formation.

So, for example, formation 4-3-3: Formation number 1: Keeper Formation number 2: Right back Formation number 3: Central defender Formation number 4: Central defender Formation number 5: Left back Formation number 6: Central midfielder Formation number 7: Central midfielder Formation number 8: Central midfielder Formation number 9: Right winger Formation number 10: Striker Formation number 11: Left winger

You can add the players to the grid according to their formation_position.

Lineup statistics

Now you have the complete lineup and formation of the teams in the fixture. If you’re interested, you can also retrieve the statistics of the players and filter only to include players that were in the starting eleven:

Example request

https://api.sportmonks.com/v3/football/fixtures/18804545?api_token=YOUR_TOKEN&include=formations;lineups.details.type&filters=lineupTypes:11

Example response

{
  "data": {
    "id": 18804545,
    "sport_id": 1,
    "league_id": 2286,
    "season_id": 19724,
    "stage_id": 77457819,
    "group_id": null,
    "aggregate_id": null,
    "round_id": null,
    "state_id": 5,
    "venue_id": 5530,
    "name": "Fiorentina vs West Ham United",
    "starting_at": "2023-06-07 19:00:00",
    "result_info": "West Ham United won after full-time.",
    "leg": "1/1",
    "details": null,
    "length": 90,
    "placeholder": false,
    "has_odds": true,
    "starting_at_timestamp": 1686164400,
    "formations": [
      {
        "id": 426436,
        "fixture_id": 18804545,
        "participant_id": 1,
        "formation": "4-2-3-1",
        "location": "away"
      },
      {
        "id": 426437,
        "fixture_id": 18804545,
        "participant_id": 109,
        "formation": "4-2-1-3",
        "location": "home"
      }
    ],
    "lineups": [
      {
        "id": 3481455351,
        "sport_id": 1,
        "fixture_id": 18804545,
        "player_id": 1316,
        "team_id": 1,
        "position_id": 25,
        "formation_field": "2:2",
        "type_id": 11,
        "formation_position": 3,
        "player_name": "Kurt Zouma",
        "jersey_number": 4,
        "details": [
          {
            "id": 377632928,
            "fixture_id": 18804545,
            "player_id": 1316,
            "team_id": 1,
            "lineup_id": 3481455351,
            "type_id": 97,
            "data": {
              "value": 1
            },
            "type": {
              "id": 97,
              "name": "Blocked Shots",
              "code": "blocked-shots",
              "developer_name": "BLOCKED_SHOTS",
              "model_type": "statistic",
              "stat_group": "defensive"
            }
          },
          {
            "id": 377633263,
            "fixture_id": 18804545,
            "player_id": 1316,
            "team_id": 1,
            "lineup_id": 3481455351,
            "type_id": 105,
            "data": {
              "value": 1
            },
            "type": {
              "id": 105,
              "name": "Total Duels",
              "code": "total-duels",
              "developer_name": "TOTAL_DUELS",
              "model_type": "statistic",
              "stat_group": "offensive"
            }
          },
          {
            "id": 377632956,
            "fixture_id": 18804545,
            "player_id": 1316,
            "team_id": 1,
            "lineup_id": 3481455351,
            "type_id": 80,
            "data": {
              "value": 17
            },
            "type": {
              "id": 80,
              "name": "Passes",
              "code": "passes",
              "developer_name": "PASSES",
              "model_type": "statistic",
              "stat_group": "overall"
            }
          },
          {
            "id": 377633281,
            "fixture_id": 18804545,
            "player_id": 1316,
            "team_id": 1,
            "lineup_id": 3481455351,
            "type_id": 106,
            "data": {
              "value": 1
            },
            "type": {
              "id": 106,
              "name": "Duels Won",
              "code": "duels-won",
              "developer_name": "DUELS_WON",
              "model_type": "statistic",
              "stat_group": "offensive"
            }
          },
          {
            "id": 377633282,
            "fixture_id": 18804545,
            "player_id": 1316,
            "team_id": 1,
            "lineup_id": 3481455351,
            "type_id": 107,
            "data": {
              "value": 1
            },
            "type": {
              "id": 107,
              "name": "Aerials Won",
              "code": "aeriels-won",
              "developer_name": "AERIALS_WON",
              "model_type": "statistic",
              "stat_group": "overall"
            }
          },
//And more

Are you interested in more information about statistics or filtering? Check our below tutorials.

• Statistics tutorial

• Filtering tutorial

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.

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.