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
Example response
​​https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=
formations
{
  "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
Example response
​​https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=
formations;lineups
{
  "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.
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
Example response
https://api.sportmonks.com/v3/football/fixtures/18804545?api_token=YOUR_TOKEN&include=formations;lineups.details.type&filters=lineupTypes:11
{
  "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.
Fixtures
Statistics
Last modified 6d ago