GET /statistics — player rankings and team performance

The Statistics API aggregates all match and player data for a season into a single response. It covers global league totals (matches played, goals, cards, clean sheets), individual player rankings (top scorers, most yellow and red cards), and team performance rankings across five categories. When no season_id is supplied, statistics are scoped to the active season automatically.

Get statistics

GET /statistics

Returns global league stats, individual player rankings, and team performance rankings for a season.

Query parameters

season_id

integer

Season to retrieve statistics for. Defaults to the currently active season when omitted.

Response

Player stats
Team stats

The individualRankings object contains three lists, each capped at the top 5 entries.

individualRankings

object

required

Hide properties

topScorers

object[]

Players sorted by goals scored, descending.

Show player entry properties

integer

Player ID.

name

string

Player name.

photo_url

string

Player photo URL.

team_name

string

Current team name for this season.

value

integer

Goals scored.

topYellowCards

object[]

Players with at least one yellow card, sorted descending.

Show player entry properties

integer

Player ID.

name

string

Player name.

photo_url

string

Player photo URL.

team_name

string

Current team name for this season.

value

integer

Yellow cards received.

topRedCards

object[]

Players with at least one red card, sorted descending.

Show player entry properties

integer

Player ID.

name

string

Player name.

photo_url

string

Player photo URL.

team_name

string

Current team name for this season.

value

integer

Red cards received.

The teamRankings object contains five sorted lists, each capped at the top 5 entries. Team objects share the same shape across all lists.

teamRankings

object

required

Hide properties

mostWins

object[]

Teams sorted by wins, descending.

mostLosses

object[]

Teams sorted by losses, descending.

mostDraws

object[]

Teams sorted by draws, descending.

bestOffense

object[]

Teams sorted by goals scored, descending.

bestDefense

object[]

Teams sorted by goals conceded, ascending (fewest first).

Each team entry in the ranking lists contains:

integer

Team ID.

name

string

Team name.

logo_url

string

Team logo URL.

won

integer

Matches won.

lost

integer

Matches lost.

drawn

integer

Matches drawn.

goals_for

integer

Goals scored.

goals_against

integer

Goals conceded.

Global stats fields

global

object

required

Aggregate totals for all finalised matches in the season.

Show properties

matchesPlayed

integer

Total number of finalised matches.

totalGoals

integer

Sum of all goals scored across all matches.

avgGoals

number

Average goals per match (2 decimal places).

totalYellows

integer

Total yellow cards across all teams.

totalReds

integer

Total red cards across all teams.

totalCleanSheets

integer

Matches where at least one team kept a clean sheet (home goals = 0 or away goals = 0).

Examples

curl https://api.example.com/statistics

curl "https://api.example.com/statistics?season_id=2"

Example response

{
  "global": {
    "matchesPlayed": 24,
    "totalGoals": 183,
    "avgGoals": 7.63,
    "totalYellows": 41,
    "totalReds": 3,
    "totalCleanSheets": 5
  },
  "teamRankings": {
    "mostWins": [
      {
        "id": 1,
        "name": "FC Example",
        "logo_url": "https://res.cloudinary.com/.../logo.jpg",
        "won": 8,
        "lost": 1,
        "drawn": 0,
        "goals_for": 38,
        "goals_against": 14
      }
    ],
    "mostLosses": [],
    "mostDraws": [],
    "bestOffense": [],
    "bestDefense": []
  },
  "individualRankings": {
    "topScorers": [
      {
        "id": 7,
        "name": "Carlos López",
        "photo_url": "https://res.cloudinary.com/.../photo.jpg",
        "team_name": "FC Example",
        "value": 14
      }
    ],
    "topYellowCards": [
      {
        "id": 12,
        "name": "Pedro Martínez",
        "photo_url": null,
        "team_name": "Los Rápidos",
        "value": 4
      }
    ],
    "topRedCards": []
  }
}

Get user ranking

GET /statistics/user-ranking

Returns the top 10 users ranked by their prediction (porra) points for a season.

Query parameters

season_id

integer

Season to rank users for. Defaults to the active season.

Response

[
  { "id": 5, "username": "fan_user", "points": 27 },
  { "id": 9, "username": "another_fan", "points": 21 }
]

Get user prediction stats

GET /statistics/user-stats

Returns the authenticated user’s prediction points, global ranking position, and their last 20 match prediction records for the season.

Requires user authentication. Include a valid Authorization: Bearer <token> header.

Query parameters

season_id

integer

Season to retrieve stats for. Defaults to the active season.

Response

totalPoints

integer

Total prediction points earned in the season.

globalRank

integer

User’s rank among all users with points in the season. 0 if the user has no points.

history

object[]

Last 20 match predictions, ordered by match date descending.

Show history entry properties

match_id

integer

Match ID.

my_prediction

string

"local", "visitante", or "empate".

real_result

string

"local", "visitante", "empate", or "pendiente" when the match has not yet been finalised.

points_awarded

integer

Points earned for this prediction.

home_team_name

string

Home team name.

away_team_name

string

Away team name.

home_goals

integer

Home goals (null if not yet played).

away_goals

integer

Away goals (null if not yet played).

status

string

Match status: "pendiente", "en_curso", or "finalizado".

date

string

Match date/time (ISO 8601).

Authentication

Matches

Teams & Players

Administration

GET /statistics — player rankings and team performance

Get statistics

Query parameters

Response

Global stats fields

Examples

Example response

Get user ranking

Query parameters

Response

Get user prediction stats

Query parameters

Response

Build docs developers (and LLMs) love

Authentication

Matches

Teams & Players

Administration

Documentation Index

​Get statistics

​Query parameters

​Response

​Global stats fields

​Examples

​Example response

​Get user ranking

​Query parameters

​Response

​Get user prediction stats

​Query parameters

​Response

Build docs developers (and LLMs) love

Get statistics

Query parameters

Response

Global stats fields

Examples

Example response

Get user ranking

Query parameters

Response

Get user prediction stats

Query parameters

Response