Skip to navigation

Soccer

The Premier League, LaLiga, Bundesliga, Serie A and Ligue 1, field by field. The live state, match minute, events and box score.

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:

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.

FieldWhat it is
period1 and 2 are the halves, 3 and 4 the halves of extra time, and 5 the penalty shoot-out.
clock_secondsAlways null, because a soccer clock counts up. The match minute is in soccer.minute.
clock_runningtrue 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_idAlways null.
soccer.minute, soccer.added_minuteThe clock as shown, so 90’+6’ is minute 90 and added minute 6. Both are null after full time.
soccer.added_time_announcedThe minutes of stoppage time the fourth official announced for the current period.
soccer.home_formation, soccer.away_formationEach team’s formation, such as 4-2-3-1.
soccer.home_red_cards, soccer.away_red_cardsRed cards each team has had.
soccer.home_shootout, soccer.away_shootoutPenalties 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, unedited:

{
"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 labels the periods, and the clock section 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 shows how to page. An event’s type and its soccer.play_type are the same value, one of these:

play_typeThe event
goal, own_goal, penalty_goalA goal
penalty_missed, penalty_savedA penalty that didn’t go in. A penalty off the woodwork is penalty_missed.
shot_on_target, shot_off_target, shot_blocked, shot_woodworkA shot that didn’t score
foul, handball, offside, cornerWhat the name says
yellow_card, red_cardA card
substitutionA substitution
var_decisionA VAR review that confirmed or cancelled the referee’s decision
goal_disallowedA goal taken away after a review
delay_start, delay_endPlay stopped, and play restarted
period_start, period_endKickoff, halftime, full time and the starts and ends of extra time and a shoot-out
otherAnything else

The soccer block on each event:

FieldWhat it is
minute, added_minuteThe 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_shootoutA shoot-out kick.
body_partWhat a shot or goal was struck with: left_foot, right_foot, head or other. null when the feed doesn’t say.
field_x, field_yWhere the event happened.
end_x, end_yWhere 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:

{
"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:

CodeWhat it is
appearances1 if the player played, 0 for an unused substitute
sub_ins1 if the player came on as a substitute
total_goals, goal_assists, own_goalsGoals, assists and own goals
total_shots, shots_on_targetShots, and shots on target
offsidesTimes caught offside
fouls_committed, fouls_sufferedFouls committed and drawn
yellow_cards, red_cardsCards
savesSaves. Goalkeepers only.
goals_concededGoals the player’s team conceded while the player was on the pitch
shots_facedShots faced

Treat every code as optional, and ignore codes you don’t use. Build a scoreboard 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

DataWhat you get today
InjuriesGET /v1/{league}/injuries returns an empty list in every soccer league.
shots_faced in the box score0 on every line in the recorded matches, goalkeepers’ included. Use saves and goals_conceded.

Coverage by league 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.