> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://statpad.dev/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://statpad.dev/docs/_mcp/server.

# Soccer

> How Statpad describes soccer matches in the Premier League, LaLiga, Bundesliga, Serie A and Ligue 1, including the soccer live state, the match minute, event types, pitch positions and player stat codes.

Statpad serves five soccer leagues: the Premier League (`epl`), LaLiga (`laliga`), the Bundesliga (`bundesliga`), Serie A (`seriea`) and Ligue 1 (`ligue1`). All five fill the same endpoints and the same fields, with the sport's details in the `soccer` blocks, so the same code reads every league.

The examples come from five recorded matches, one per league, all played on November 8, 2026:

| League         | Match                                                                                                 | Final |
| -------------- | ----------------------------------------------------------------------------------------------------- | ----- |
| Premier League | [Manchester United v Aston Villa](https://statpad.dev/samples/epl-man-utd-aston-villa/plays.json)     | 4-4   |
| LaLiga         | [Atlético Madrid v Barcelona](https://statpad.dev/samples/laliga-atletico-barcelona/plays.json)       | 1-2   |
| Bundesliga     | [FC Cologne v Bayer Leverkusen](https://statpad.dev/samples/bundesliga-cologne-leverkusen/plays.json) | 1-2   |
| Serie A        | [Fiorentina v Juventus](https://statpad.dev/samples/seriea-fiorentina-juventus/plays.json)            | 2-2   |
| Ligue 1        | [Lens v Marseille](https://statpad.dev/samples/ligue1-lens-marseille/plays.json)                      | 1-2   |

The home team is first, as soccer writes a match.

## Live state

`live_state` on `GET /v1/{league}/games/{id}` carries the situation in its `soccer` block. The other sports' blocks are `null`.

| Field                                            | What it is                                                                                                                                     |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `period`                                         | 1 and 2 are the halves, 3 and 4 the halves of extra time, and 5 the penalty shoot-out.                                                         |
| `clock_seconds`                                  | Always `null`, because a soccer clock counts up. The match minute is in `soccer.minute`.                                                       |
| `clock_running`                                  | `true` while a half or a period of extra time is being played, and `false` otherwise, such as at halftime, in a shoot-out and after full time. |
| `possession_team_id`                             | Always `null`.                                                                                                                                 |
| `soccer.minute`, `soccer.added_minute`           | The clock as shown, so 90'+6' is minute `90` and added minute `6`. Both are `null` after full time.                                            |
| `soccer.added_time_announced`                    | The minutes of stoppage time the fourth official announced for the current period.                                                             |
| `soccer.home_formation`, `soccer.away_formation` | Each team's formation, such as `4-2-3-1`.                                                                                                      |
| `soccer.home_red_cards`, `soccer.away_red_cards` | Red cards each team has had.                                                                                                                   |
| `soccer.home_shootout`, `soccer.away_shootout`   | Penalties each team has scored in a shoot-out. `null` until one starts.                                                                        |

This is the Premier League match's live state after full time, from [`game.json`](https://statpad.dev/samples/epl-man-utd-aston-villa/game.json), unedited:

```json
{
  "away_score": 4,
  "baseball": null,
  "basketball": null,
  "clock_running": false,
  "clock_seconds": null,
  "football": null,
  "game_id": "01a1eee7-199e-7db2-99d7-b07cfeb058aa",
  "hockey": null,
  "home_score": 4,
  "last_play_id": "01a1eee7-199f-726c-9773-827460257d82",
  "period": 2,
  "period_half": null,
  "possession_team_id": null,
  "soccer": {
    "added_minute": null,
    "added_time_announced": null,
    "away_formation": "4-2-3-1",
    "away_red_cards": 0,
    "away_shootout": null,
    "home_formation": "4-2-3-1",
    "home_red_cards": 0,
    "home_shootout": null,
    "minute": null
  },
  "updated_at": "2026-11-18T13:44:45.213136Z",
  "version": 1
}
```

## Periods, extra time and shoot-outs

Every soccer league has a `period_kind` of `half` and 2 `regulation_periods`. A league match has two halves. Periods 3 to 5 appear only in a match that goes to extra time or a shoot-out. [Build a scoreboard](/docs/scoreboard#the-period) labels the periods, and [the clock section](/docs/scoreboard#the-clock) formats the match minute.

A shoot-out kick is a `penalty_goal`, `penalty_missed` or `penalty_saved` event in period 5 with `soccer.is_shootout` set. It never counts toward the score. The shoot-out's score is in the live state's `home_shootout` and `away_shootout`.

## Events

`GET /v1/{league}/games/{id}/plays` lists the match's events. It returns a page of events, 500 by default and up to 1,000 with `limit`, with a `next_cursor` for the rest. [Lists, pagination and dates](/docs/pagination) shows how to page. An event's `type` and its `soccer.play_type` are the same value, one of these:

| `play_type`                                                          | The event                                                                          |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `goal`, `own_goal`, `penalty_goal`                                   | A goal                                                                             |
| `penalty_missed`, `penalty_saved`                                    | A penalty that didn't go in. A penalty off the woodwork is `penalty_missed`.       |
| `shot_on_target`, `shot_off_target`, `shot_blocked`, `shot_woodwork` | A shot that didn't score                                                           |
| `foul`, `handball`, `offside`, `corner`                              | What the name says                                                                 |
| `yellow_card`, `red_card`                                            | A card                                                                             |
| `substitution`                                                       | A substitution                                                                     |
| `var_decision`                                                       | A VAR review that confirmed or cancelled the referee's decision                    |
| `goal_disallowed`                                                    | A goal taken away after a review                                                   |
| `delay_start`, `delay_end`                                           | Play stopped, and play restarted                                                   |
| `period_start`, `period_end`                                         | Kickoff, halftime, full time and the starts and ends of extra time and a shoot-out |
| `other`                                                              | Anything else                                                                      |

The `soccer` block on each event:

| Field                    | What it is                                                                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `minute`, `added_minute` | The match minute shown for the event and the stoppage minute after it. `null` when the feed shows no time, as for a kickoff or a shoot-out kick. |
| `is_shootout`            | A shoot-out kick.                                                                                                                                |
| `body_part`              | What a shot or goal was struck with: `left_foot`, `right_foot`, `head` or `other`. `null` when the feed doesn't say.                             |
| `field_x`, `field_y`     | Where the event happened.                                                                                                                        |
| `end_x`, `end_y`         | Where a shot ended.                                                                                                                              |

Positions run 0 to 100. Usually they're from the acting team's point of view, with `x` running from its own goal line to the goal line it attacks and `y` across the pitch, so a shot that scores usually ends near `end_x` 100. Statpad copies the positions from the feed as it sends them, and the feed doesn't always follow that convention, so use them to draw events, not to decide what happened. To find goals, read `type` and `is_scoring`.

Events have no `clock_seconds` and no `group_id`. Order them by `sequence` and `id`, and label them with `minute` and `added_minute`. `team_id` is the team credited with the event, which for a shot is the shooting team.

Each event's `participants` lists the players in it with a `role`: `scorer`, `assist`, `shooter`, `fouler`, `fouled`, `player_in` and `player_out` on a substitution, `passer` on an offside, or `player` for any other part. An offside's one participant is the player who played the pass, not the player caught offside. Join each participant's `player_id` to `players[].id` in the game roster response, not to the box score, because a player in a play can have no stat line.

Statpad writes each event's `description` from its fields, in English. Read the structured fields rather than parsing the text, whose wording can change.

This is the first goal of the Premier League match, from `plays.json`, unedited:

```json
{
  "away_score": 1,
  "baseball": null,
  "basketball": null,
  "clock_seconds": null,
  "description": "Goal: Alysson (Aston Villa), left foot, assisted by John McGinn. Manchester United 0, Aston Villa 1.",
  "football": null,
  "game_id": "01a1eee7-199e-7db2-99d7-b07cfeb058aa",
  "group_id": null,
  "hockey": null,
  "home_score": 0,
  "id": "01a1eee7-199f-7002-b9e4-48cab560daa9",
  "is_official": true,
  "is_scoring": true,
  "participants": [
    {
      "player_id": "01a1eee7-199e-7ecb-a396-8914a61005a6",
      "role": "assist",
      "team_id": "01a1eee7-199e-7dd0-b3af-8a700fc30fee"
    },
    {
      "player_id": "01a1eee7-199e-7eef-a1d2-0150ce16fb93",
      "role": "scorer",
      "team_id": "01a1eee7-199e-7dd0-b3af-8a700fc30fee"
    }
  ],
  "period": 1,
  "period_half": null,
  "points": 1,
  "sequence": 1794155574000,
  "soccer": {
    "added_minute": null,
    "body_part": "left_foot",
    "end_x": 100,
    "end_y": 48.4,
    "field_x": 90.8,
    "field_y": 34.2,
    "is_shootout": false,
    "minute": 1,
    "play_type": "goal"
  },
  "team_id": "01a1eee7-199e-7dd0-b3af-8a700fc30fee",
  "type": "goal",
  "updated_at": "2026-11-18T13:44:45.213136Z",
  "version": 1,
  "wall_clock": "2026-11-08T16:32:54Z"
}
```

Alysson scored for Aston Villa in the 1st minute with his left foot, from `field_x` 90.8 and `field_y` 34.2, and John McGinn assisted.

## Play groups

Soccer has no drives or possessions in the data. `GET /v1/{league}/games/{id}/play-groups` returns an empty list.

## Box score

`GET /v1/{league}/games/{id}/boxscore` has one line for every player in the match squad, unused substitutes included. Each line holds one category, `soccer`:

| Code                                       | What it is                                                         |
| ------------------------------------------ | ------------------------------------------------------------------ |
| `appearances`                              | `1` if the player played, `0` for an unused substitute             |
| `sub_ins`                                  | `1` if the player came on as a substitute                          |
| `total_goals`, `goal_assists`, `own_goals` | Goals, assists and own goals                                       |
| `total_shots`, `shots_on_target`           | Shots, and shots on target                                         |
| `offsides`                                 | Times caught offside                                               |
| `fouls_committed`, `fouls_suffered`        | Fouls committed and drawn                                          |
| `yellow_cards`, `red_cards`                | Cards                                                              |
| `saves`                                    | Saves. Goalkeepers only.                                           |
| `goals_conceded`                           | Goals the player's team conceded while the player was on the pitch |
| `shots_faced`                              | Shots faced                                                        |

Treat every code as optional, and ignore codes you don't use. [Build a scoreboard](/docs/scoreboard#build-a-box-score) joins the lines to player names.

## Rosters

`GET /v1/{league}/games/{id}/roster` lists both match squads, with each player's team, jersey, position for the match, such as `G`, `RB` or `AM-L`, and whether they started. Positions are the feed's codes, so treat them as display text.

## What isn't filled yet

| Data                           | What you get today                                                                                  |
| ------------------------------ | --------------------------------------------------------------------------------------------------- |
| Injuries                       | `GET /v1/{league}/injuries` returns an empty list in every soccer league.                           |
| `shots_faced` in the box score | `0` on every line in the recorded matches, goalkeepers' included. Use `saves` and `goals_conceded`. |

[Coverage by league](/docs/coverage#not-filled-yet) lists the gaps every sport shares, such as team totals and the score by period.

## League differences

The five leagues fill the same fields. Their recorded matches have the same live state fields, the same 15 box score codes and the same event types, apart from events that simply didn't happen in a given match, such as a handball.