Statistics API — season stats, rankings, and predictions

The Statistics API aggregates performance data across the full season into three focused endpoints. The main statistics endpoint returns match-level globals, team performance rankings across five categories, and top-five individual rankings for scorers and card recipients. Two additional endpoints power the prediction (porra) leaderboard: a public ranking of the top ten users by season points and a private endpoint that returns an authenticated user’s own score, global rank, and full vote history.

Season statistics

GET /statistics Returns global match statistics, team performance rankings (top 5 per category), and individual player rankings for the requested season.

season_id

number

Season to query. Defaults to the currently active season.

Response

global

object

Season-level aggregates across all finalized matches.

Show properties

matchesPlayed

number

Total finalized matches.

totalGoals

number

Sum of all goals scored.

avgGoals

number

Average goals per match (rounded to 2 decimal places).

totalYellows

number

Total yellow cards issued.

totalReds

number

Total red cards issued.

totalCleanSheets

number

Matches where at least one team kept a clean sheet.

teamRankings

object

Top-5 team lists per performance category. Each array contains team objects with id, name, logo_url, and the relevant stat field.

Show properties

mostWins

array

Teams sorted by wins descending.

mostLosses

array

Teams sorted by losses descending.

mostDraws

array

Teams sorted by draws descending.

bestOffense

array

Teams sorted by goals scored descending.

bestDefense

array

Teams sorted by goals conceded ascending (fewer is better).

individualRankings

object

Top-5 player lists per ranking type.

Show properties

topScorers

array

Players sorted by goals descending.

topYellowCards

array

Players with at least one yellow card, sorted descending.

topRedCards

array

Players with at least one red card, sorted descending.

Each entry in an individual ranking array has the following shape:

{
  "id": 15,
  "name": "Adrián López",
  "photo_url": "https://res.cloudinary.com/example/adrian.webp",
  "team_name": "FC Rayo",
  "value": 8
}

Example curl

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

Example response

{
  "global": {
    "matchesPlayed": 24,
    "totalGoals": 186,
    "avgGoals": 7.75,
    "totalYellows": 43,
    "totalReds": 5,
    "totalCleanSheets": 8
  },
  "teamRankings": {
    "mostWins": [
      { "id": 3, "name": "FC Rayo", "logo_url": null, "won": 7, "lost": 1, "drawn": 0, "goals_for": 52, "goals_against": 18 }
    ],
    "mostLosses": [
      { "id": 12, "name": "Último FC", "logo_url": null, "won": 0, "lost": 8, "drawn": 0, "goals_for": 12, "goals_against": 60 }
    ],
    "mostDraws": [],
    "bestOffense": [
      { "id": 3, "name": "FC Rayo", "logo_url": null, "won": 7, "lost": 1, "drawn": 0, "goals_for": 52, "goals_against": 18 }
    ],
    "bestDefense": [
      { "id": 3, "name": "FC Rayo", "logo_url": null, "won": 7, "lost": 1, "drawn": 0, "goals_for": 52, "goals_against": 18 }
    ]
  },
  "individualRankings": {
    "topScorers": [
      { "id": 15, "name": "Adrián López", "photo_url": null, "team_name": "FC Rayo", "value": 8 }
    ],
    "topYellowCards": [
      { "id": 22, "name": "Marcos Ruiz", "photo_url": null, "team_name": "Atlético Sur", "value": 4 }
    ],
    "topRedCards": [
      { "id": 9, "name": "Juan Gómez", "photo_url": null, "team_name": "Deportivo Norte", "value": 2 }
    ]
  }
}

User prediction leaderboard

GET /statistics/user-ranking Returns the top 10 users ranked by their prediction (porra) points for the requested season. Only accounts with role user are included; referee and admin accounts are excluded.

season_id

number

Season to query. Defaults to the currently active season.

Response — array of up to 10 user objects:

number

User ID.

username

string

Display username.

points

number

Total prediction points earned this season. 0 if the user has not voted.

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

[
  { "id": 4, "username": "futbol_fan_99", "points": 18 },
  { "id": 11, "username": "la_porra_reina", "points": 16 },
  { "id": 7, "username": "goleador_x", "points": 14 }
]

Personal voting stats

GET /statistics/user-stats Returns the authenticated user’s total prediction points, their global rank in the leaderboard, and their 20 most recent votes for the season with match results and points awarded. Requires authentication.

season_id

number

Season to query. Defaults to the currently active season.

Response

totalPoints

number

Season prediction points for the current user.

globalRank

number

Rank position in the full leaderboard. 0 if the user has no votes yet.

history

array

Up to 20 most recent prediction records, ordered by match date descending.

Show history entry

my_prediction

string

local | empate | visitante

points_awarded

number | null

1 if correct, 0 if wrong, null if the match is not yet finalized.

match_id

number

Match ID.

home_goals

number | null

Goals scored by the home team.

away_goals

number | null

Goals scored by the away team.

status

string

Match status at query time.

date

string

Match datetime.

home_team_name

string

Home team name.

away_team_name

string

Away team name.

real_result

string

local | empate | visitante | pendiente

curl "https://api.example.com/statistics/user-stats" \
  -H "Authorization: Bearer <token>"

{
  "totalPoints": 12,
  "globalRank": 3,
  "history": [
    {
      "my_prediction": "local",
      "points_awarded": 1,
      "match_id": 42,
      "home_goals": 3,
      "away_goals": 1,
      "status": "finalizado",
      "date": "2025-11-15T19:00:00",
      "home_team_name": "FC Rayo",
      "away_team_name": "Atlético Sur",
      "real_result": "local"
    },
    {
      "my_prediction": "empate",
      "points_awarded": 0,
      "match_id": 39,
      "home_goals": 2,
      "away_goals": 4,
      "status": "finalizado",
      "date": "2025-11-08T19:00:00",
      "home_team_name": "Deportivo Norte",
      "away_team_name": "FC Rayo",
      "real_result": "visitante"
    }
  ]
}

Points are awarded automatically when a match is finalized via PUT /matches/:id/finish. The leaderboard reflects the updated totals immediately.

Authentication

League Data

Administration

Statistics API — season stats, rankings, and predictions

Season statistics

User prediction leaderboard

Personal voting stats

Build docs developers (and LLMs) love

Authentication

League Data

Administration

Documentation Index

​Season statistics

​User prediction leaderboard

​Personal voting stats

Build docs developers (and LLMs) love

Season statistics

User prediction leaderboard

Personal voting stats