Skip to content
StatsCore / Developers

Lineups and formations

Not every match has a scouted formation, and the flag that tells you so is easy to miss because it sits in a generic list, not on its own field.

has_formations is a detail, and it has three states

Section titled “has_formations is a detail, and it has three states”

GET /v2/events/{id} reports it inside details[], alongside every other per-match flag:

{ "id": 178, "name": "Has formations", "code": "has_formations", "value": "yes" }
ValueMeaning
"no"no formation for this match
"soon"a scout is entering it now - poll again in a few minutes
"yes"formation and positions are available

The team's formation

Section titled “The team's formation”

A text stat on each participant, verified on a real match (Ekstraklasa, event_id: 5928182):

{ "id": 716, "short_name": "Form.", "name": "Formation", "code": "formation", "value": "3-5-2" }

Match on code: "formation", not on position in the array - see the statistics traps in recipe 03 for why. The set of possible values is the sport's own formations list on the data reference (18 for soccer, from 4-4-2 to 5-4-1).

Where a player stands: lineups[], not a stat

Section titled “Where a player stands: lineups[], not a stat”

This is where the current API has moved past what is written about it elsewhere: player_position lives directly on each entry of the event's own lineups[] array, not inside a sub-participant stat.

{
  "id": 13115601,
  "type": "player",
  "position": "bench",
  "bench": "yes",
  "shirt_nr": "13",
  "participant_id": 971040,
  "participant_name": "Josep Martinez",
  "player_position": null
}

player_position is null for every bench entry and an integer 1-11 for the starting eleven - confirmed on the match above, 22 non-null values across both teams, nothing outside that range. Numbering starts at the goalkeeper and continues right to left across the formation, so 1 is always the keeper regardless of which formation string participants[].stats reports.

Push updates exist, out of scope here

Section titled “Push updates exist, out of scope here”

STATSCORE can also push formation and position changes after kickoff over AMQP (team_formation and player_position messages). This portal does not cover the AMQP/ScoutsFeed integration yet - see the recipes overview for what is and is not covered so far.

Next

Section titled “Next”