Overview

Returns a team’s season data from Understat, including fixtures/results, player performance, and aggregate statistics by match situation, formation, game state, timing, shot zone, attack speed, and result type.

Inputs

team — string, optional. Team name or identifier used by the Understat endpoint. Example: Arsenal.
year — number, optional. Season year. Example: 2023.

Response

Returns a JSON object with these top-level fields:

dates — array of match records. Each record includes match and team identifiers, home/away teams, goals, expected goals (xG), date/time, win/draw/loss forecast probabilities, and result.
players — array of player-season records. Each record includes player identity, appearances and minutes, goals, expected goals and assists, shots, key passes, cards, position, and build-up metrics.
statistics — object containing aggregate team statistics grouped by:
situation
formation
gameState
timing
shotZone
attackSpeed
result

Statistics entries include counts such as shots and goals, an xG value, and corresponding against metrics.

Large arrays may be truncated in displayed responses. The verified test response indicated datatruncated: true and included truncation metadata such as datachars, datacap, and datatruncation; this reflects response display limits rather than the endpoint’s underlying data model.

Auth & browser

Authentication is not required by the endpoint configuration. Browser context, fetch mode, and context-aware requests are not enabled.

Examples

Minimal request:

{
  "team": "Arsenal",
  "year": 2023
}

Verified success response shape:

{
  "dates": [
    {
      "id": "22276",
      "isResult": true,
      "side": "h",
      "h": { "id": "83", "title": "Arsenal", "short_title": "ARS" },
      "a": { "id": "249", "title": "Nottingham Forest", "short_title": "NOT" },
      "goals": { "h": "2", "a": "1" },
      "xG": { "h": "0.84262", "a": "0.966305" },
      "datetime": "2023-08-12 11:30:00",
      "forecast": { "w": 0.30280789705352503, "d": 0.3269645004119555, "l": 0.37022760230430773 },
      "result": "w"
    }
  ],
  "players": [
    {
      "id": "7322",
      "player_name": "Bukayo Saka",
      "games": "35",
      "time": "2990",
      "goals": "16",
      "xG": "16.807056225836277",
      "assists": "8",
      "position": "F",
      "team_title": "Arsenal"
    }
  ],
  "statistics": {
    "situation": { "OpenPlay": { "shots": 502, "goals": 62, "xG": 65.27158057270572 } },
    "formation": { "4-3-3": { "stat": "4-3-3", "time": 3598, "shots": 645, "goals": 91 } }
  }
}

The live response contains additional match, player, and statistics entries; the example is shortened to show the returned structure.

Notes

Match and player numeric values are returned as strings in the verified response, while aggregate statistic values are numeric.
The endpoint response includes historical fixtures/results as well as season aggregates.
Availability and completeness may depend on the team name and season supplied.