Standings and statistics API endpoints

The standings and statistics endpoints expose all competition data derived from finished matches: group-stage tables, season-wide totals, individual and team rankings, and the match-prediction leaderboard.

GET /standings

Returns the group-stage standings table for a season. Results are cached in Redis for one hour and invalidated automatically when a match is finished. The response includes:

A groups map keyed by group name, each containing an array of teams sorted by the tiebreaker rules (head-to-head points → head-to-head goal difference → overall goal difference → goals scored → goals conceded).
A fourthPlacesRanking array that compares the best fourth-placed teams across groups using equalised statistics (the result against the last-placed team in the group is excluded where groups have unequal sizes).
bestFourthId — the identifier of the best fourth-placed team overall.

season_id

number

Season to fetch standings for. Defaults to the currently active season when omitted.

Request
Response

cURL

curl "http://localhost:3000/standings?season_id=3"

{
  "groups": {
    "Grupo A": [
      {
        "group_id": 1,
        "group_name": "Grupo A",
        "id": 7,
        "team_name": "Rayo Vallecas FC",
        "team_logo": "https://res.cloudinary.com/.../logo.webp",
        "points": 13,
        "played": 5,
        "won": 4,
        "drawn": 1,
        "lost": 0,
        "goals_for": 18,
        "goals_against": 7,
        "goal_difference": 11,
        "yellow_cards": 2,
        "red_cards": 0
      }
    ]
  },
  "bestFourthId": 22,
  "fourthPlacesRanking": [
    {
      "id": 22,
      "team_name": "CD Muralla",
      "points": 6,
      "played": 4,
      "goal_difference": 2
    }
  ]
}

Response fields

groups

object

Map of group name → ordered array of team standing rows.

Show team standing properties

group_id

number

Group identifier.

group_name

string

Group name.

number

Team identifier.

team_name

string

Team name.

team_logo

string | null

Team logo URL.

points

number

Points total.

played

number

Matches played.

won

number

Matches won.

drawn

number

Matches drawn.

lost

number

Matches lost.

goals_for

number

Goals scored.

goals_against

number

Goals conceded.

goal_difference

number

Goal difference (goals_for − goals_against).

yellow_cards

number

Yellow cards received.

red_cards

number

Red cards received.

bestFourthId

number | null

Identifier of the best fourth-placed team, used to highlight the playoff qualifier. null when fewer than four groups exist.

fourthPlacesRanking

object[]

Ranked array of fourth-placed teams with equalised statistics for cross-group comparison.

GET /statistics

Returns global season statistics, team rankings, and individual player rankings. Defaults to the active season when season_id is omitted.

season_id

number

Season to compute statistics for. Defaults to the active season.

Request
Response

cURL

curl "http://localhost:3000/statistics?season_id=3"

{
  "global": {
    "matchesPlayed": 24,
    "totalGoals": 98,
    "avgGoals": 4.08,
    "totalYellows": 31,
    "totalReds": 4,
    "totalCleanSheets": 7
  },
  "teamRankings": {
    "mostWins": [
      { "id": 7, "name": "Rayo Vallecas FC", "logo_url": "...", "won": 8, "lost": 1, "drawn": 1, "goals_for": 32, "goals_against": 12 }
    ],
    "mostLosses": [...],
    "mostDraws": [...],
    "bestOffense": [...],
    "bestDefense": [...]
  },
  "individualRankings": {
    "topScorers": [
      { "id": 5, "name": "Luis García", "photo_url": "...", "team_name": "Rayo Vallecas FC", "value": 12 }
    ],
    "topYellowCards": [...],
    "topRedCards": [...]
  }
}

Response fields

global

object

Aggregated stats across all finished matches in the season.

Show properties

matchesPlayed

number

Number of finished matches.

totalGoals

number

Total goals scored across all matches.

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

Number of matches where at least one team kept a clean sheet.

teamRankings

object

Each property is an array of up to 5 teams sorted by the respective criterion.

Show properties

mostWins

object[]

Teams with the most wins.

mostLosses

object[]

Teams with the most losses.

mostDraws

object[]

Teams with the most draws.

bestOffense

object[]

Teams with the most goals scored.

bestDefense

object[]

Teams with the fewest goals conceded.

Each team entry contains id, name, logo_url, won, lost, drawn, goals_for, and goals_against.

individualRankings

object

Each property is an array of up to 5 players.

Show properties

topScorers

object[]

Players ordered by goals scored descending.

topYellowCards

object[]

Players with at least one yellow card, ordered by count descending.

topRedCards

object[]

Players with at least one red card, ordered by count descending.

Each player entry contains id, name, photo_url, team_name, and value (the counted stat).

GET /statistics/user-ranking

Returns the top 10 users ranked by prediction points for a season. Only accounts with the user role are included.

season_id

number

Season identifier. Defaults to the active season.

Request
Response

cURL

curl "http://localhost:3000/statistics/user-ranking?season_id=3"

[
  { "id": 101, "username": "futsal_fan", "points": 17 },
  { "id": 204, "username": "prode_master", "points": 15 }
]

number

User identifier.

username

string

Username.

points

number

Prediction points earned in the season. 0 if the user has not voted on any finished matches.

GET /statistics/user-stats

Returns the authenticated user’s prediction summary for a season: their total points, global rank, and a history of their last 20 votes. Requires authentication.

season_id

number

Season identifier. Defaults to the active season.

Request
Response

cURL

curl "http://localhost:3000/statistics/user-stats?season_id=3" \
  -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-03-15T18:00:00",
      "home_team_name": "Rayo Vallecas FC",
      "away_team_name": "Atlético Sur",
      "real_result": "local"
    }
  ]
}

totalPoints

number

Total prediction points earned by the user in the season.

globalRank

number

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

history

object[]

Up to 20 most recent votes in the season, ordered by match date descending.

Show history item properties

my_prediction

string

The user’s vote: local, empate, or visitante.

points_awarded

number | null

1 if the prediction was correct, 0 if wrong, null if the match is not yet finished.

match_id

number

Match identifier.

home_goals

number | null

Home team goals. null for unfinished matches.

away_goals

number | null

Away team goals. null for unfinished matches.

status

string

Match status: pendiente, en_curso, or finalizado.

date

string

Match datetime (ISO 8601).

home_team_name

string | null

Home team name.

away_team_name

string | null

Away team name.

real_result

string

Actual match result: local, empate, visitante, or pendiente when the match is not finished.

Overview

Endpoints

Standings and statistics API endpoints

GET /standings

Response fields

GET /statistics

Response fields

GET /statistics/user-ranking

GET /statistics/user-stats

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /standings

​Response fields

​GET /statistics

​Response fields

​GET /statistics/user-ranking

​GET /statistics/user-stats

Build docs developers (and LLMs) love

GET /standings

Response fields

GET /statistics

Response fields

GET /statistics/user-ranking

GET /statistics/user-stats