Season standings

Included in all plans

Season standings are available on all base plans (Starter, Growth, Pro, Enterprise) at no additional cost. Plans differ in the number of accessible leagues and hourly API call limits.

Compare plans →

Quick summary: This tutorial covers the five standings endpoints available in API v3 (including by season, by round, live standings, and standing corrections) and shows how to enrich and filter them for real-world use in league tables and standings widgets.

What you'll learn:

• How to retrieve standings by season, round, and live league ID

• How to enrich standings responses with team names, league info, and detailed stats

• How to use standing corrections for leagues with point deductions

• How to select only the fields you need to reduce response size

Time to complete: 20 minutes Skill level: Beginner to Intermediate

Prerequisites: Authentication, Includes, Leagues and Seasons

1. When to use this feature

Standings show the ranked table of teams competing in a season, including games played, wins, losses, goals scored, goals conceded, and total points. They update after each match and can be retrieved historically by round.

Real-world use cases

• Use case 1: League table display You're building a football app and want to show the current Premier League table. GET Standings by Season ID returns the full ranked table for any season, enrichable with team names and detailed statistics.

• Use case 2: Historical round-by-round standings You want to show how a team's position changed over the course of a season. GET Standings by Round ID lets you retrieve the table as it stood at any specific round.

• Use case 3: Live league table during an active match You want the table to update in real time while matches are being played. GET Live Standings by League ID returns the current in-progress standings for any active season.

• Use case 4: Displaying point deductions A club receives a disciplinary sanction mid-season. GET Standing Corrections by Season ID provides the deduction data so you can accurately reflect the adjusted table.

When NOT to use this feature

❌ Player rankings or top scorers : Use the Topscorers endpoint for individual player standings.

❌ Expected points tables (xPTS) : Use the Expected Goals (xG) tutorial for expected-points-based standings.

2. How to retrieve data

Understanding the endpoints

Base URL:

https://api.sportmonks.com/v3/football/standings

Available endpoints:

Endpoint	Path suffix	Description
GET All Standings	(base URL)	All standings in your subscription
GET Standings by Season ID	/seasons/{season_id}	Full league table for a specific season
GET Standings by Round ID	/rounds/{round_id}	Table as it stood at a specific round
GET Standing Corrections by Season ID	/corrections/seasons/{season_id}	Point deductions for a season
GET Live Standings by League ID	/live/leagues/{league_id}	Real-time table for an active season

Available parameters:

Parameter	Type	Required	Description	Example
api_token	string	Yes	Your API authentication token	YOUR_API_TOKEN
include	string	No	Related data to attach	participant;league;details.type
select	string	No	Fields to return on includes	participant:name;league:name
filters	string	No	Filter by specific fields	standingSeasons:19686

Step-by-step implementation

Step 1: GET Standings by Season ID

This is the most commonly used standings endpoint. Pass the season_id for the season you want.

https://api.sportmonks.com/v3/football/standings/seasons/{season_id}
?api_token=YOUR_API_TOKEN

For example, the Danish Superliga 2022/2023 season (season ID: 19686):

https://api.sportmonks.com/v3/football/standings/seasons/19686
?api_token=YOUR_API_TOKEN

JavaScript:

Javascript

const apiToken = 'YOUR_API_TOKEN';

async function getStandingsBySeason(seasonId, params = {}) {
  const query = new URLSearchParams({ api_token: apiToken, ...params });
  const response = await fetch(
    `https://api.sportmonks.com/v3/football/standings/seasons/${seasonId}?${query}`
  );
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

const table = await getStandingsBySeason(19686);

Python

PHP

Step 2: GET Standings by Round ID

Returns the league table as it stood at a specific round, useful for historical analysis or "table at round N" features. You need the round_id, which you can retrieve from the Rounds by Season ID endpoint.

https://api.sportmonks.com/v3/football/standings/rounds/274241
?api_token=YOUR_API_TOKEN

Step 3: GET Live Standings by League ID

Returns the current in-progress table for an active season. Note that this endpoint takes a league_id, not a season_id, because you can only retrieve live standings for a currently active season.

https://api.sportmonks.com/v3/football/standings/live/leagues/501
?api_token=YOUR_API_TOKEN

The response will be empty if the league has no active season or no matches are currently being played in that league.

Step 4: GET Standing Corrections by Season ID

Returns point deductions applied to teams in a given season. Use this alongside the main standings to accurately display adjusted positions.

https://api.sportmonks.com/v3/football/standings/corrections/seasons/18441
?api_token=YOUR_API_TOKEN

Step 5: Adding includes

By default, standings return only IDs (participant ID, league ID, etc.) and not names. Use include to attach readable data.

https://api.sportmonks.com/v3/football/standings/seasons/19686
?api_token=YOUR_API_TOKEN&include=participant;league;details.type

The most useful includes for standings:

• participant : Team name, logo, country, and venue

• league : League name and logo

• details.type : Detailed stats per team (matches played, wins, goals, form, etc.)

Including .type is expensive and not recommended for production. Fetch all types once from the Types endpoint and cache them. Only include .type when testing or if no other option is available.

Step 6: Selecting specific fields

Use select on includes to return only the fields you need, reducing response size significantly.

https://api.sportmonks.com/v3/football/standings/seasons/19686
?api_token=YOUR_API_TOKEN&include=participant:name;league:name;details.type:name

Step 7: Complete example

Javascript

class FootballAPI {
  constructor(apiToken) {
    this.token = apiToken;
    this.baseURL = 'https://api.sportmonks.com/v3/football';
  }

  async getStandings(seasonId, params = {}) {
    const query = new URLSearchParams({ api_token: this.token, ...params });
    const r = await fetch(`${this.baseURL}/standings/seasons/${seasonId}?${query}`);
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    return r.json();
  }

  async getLiveStandings(leagueId, params = {}) {
    const query = new URLSearchParams({ api_token: this.token, ...params });
    const r = await fetch(`${this.baseURL}/standings/live/leagues/${leagueId}?${query}`);
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    return r.json();
  }
}

const api = new FootballAPI('YOUR_API_TOKEN');

const table = await api.getStandings(19686, {
  include: 'participant:name,image_path;details.type:name'
});

const liveTable = await api.getLiveStandings(501, {
  include: 'participant:name'
});

Python

PHP

3. Working with the data

Understanding the response structure

{
  "data": [
    {
      "id": 2622,
      "participant_id": 53,
      "sport_id": 1,
      "league_id": 501,
      "season_id": 19735,
      "stage_id": 77457866,
      "group_id": null,
      "round_id": 275092,
      "standing_rule_id": 13224,
      "position": 1,
      "result": "equal",
      "points": 73
    }
  ]
}

Key fields:

Field	Type	Description
id	integer	Unique standing record ID
participant_id	integer	The team's ID, use with include=participant to get the name
position	integer	Current league position
result	string	Position change: "up", "down", or "equal"
points	integer	Total points accumulated
round_id	integer	The most recent round this standing reflects
standing_rule_id	integer	The tiebreaker rule applied at this position

With include=details.type, each team object gains a details array where each entry represents a stat (matches played, wins, goals for, etc.) identified by type_id.

Processing the data

Build a sorted league table with team names:

const data = await api.getStandings(19686, {
  include: 'participant:name,image_path'
});

const table = data.data
  .sort((a, b) => a.position - b.position)
  .map(row => ({
    position: row.position,
    team: row.participant?.name || `Team ${row.participant_id}`,
    logo: row.participant?.image_path,
    points: row.points,
    trend: row.result
  }));

console.table(table);

Extract a specific stat from details (e.g. matches played, type_id 129):

function getStat(details, typeId) {
  return details?.find(d => d.type_id === typeId)?.value ?? 0;
}

const enriched = data.data.map(row => ({
  team: row.participant?.name,
  position: row.position,
  points: row.points,
  played: getStat(row.details, 129),
  won: getStat(row.details, 130),
  drawn: getStat(row.details, 131),
  lost: getStat(row.details, 132)
}));

4. Common pitfalls

Pitfall 1: Using GET All Standings instead of by Season ID

GET All Standings returns every standing across every league in your subscription (thousands of records). Always use GET Standings by Season ID for a specific table.

// ❌ Wrong: returns far more data than you need
const all = await fetch('/standings?api_token=...');

// ✅ Correct: returns only the season you need
const table = await fetch('/standings/seasons/19686?api_token=...');

Pitfall 2: Including .type on every request

Including details.type on standings triggers a type resolution for every stat on every team. This is expensive at scale.

// ❌ Avoid in production
const table = await api.getStandings(19686, { include: 'details.type' });

// ✅ Fetch types once, then use IDs directly
const types = await fetchAndCacheTypes();
const table = await api.getStandings(19686, { include: 'details' });
// Resolve type names locally: types.get(detail.type_id)

Pitfall 3: Using live standings for historical data

GET Live Standings only works for currently active seasons. For historical or completed season data, use GET Standings by Season ID.

// ❌ Wrong: will return nothing for a finished season
const old = await fetch('/standings/live/leagues/501?api_token=...');

// ✅ Correct: historical tables use season ID
const old = await fetch('/standings/seasons/19686?api_token=...');

Pitfall 4: Not handling group standings (cup competitions)

In cup competitions and leagues with group stages, standings are returned per group. Always check group_id in the response and handle both cases.

const isGroupStage = data.data.some(row => row.group_id !== null);

if (isGroupStage) {
  const groups = {};
  for (const row of data.data) {
    const key = row.group_id;
    if (!groups[key]) groups[key] = [];
    groups[key].push(row);
  }
} else {
  renderTable(data.data.sort((a, b) => a.position - b.position));
}

5. Advanced usage

Advanced technique 1: Round-by-round position tracking

Show a team's position across every round of the season to visualise their trajectory.

async function getTeamPositionHistory(rounds, teamId) {
  const requests = rounds.map(roundId =>
    api.getStandingsByRound(roundId, { include: 'participant:name' })
  );

  const results = await Promise.all(requests);

  return results.map((result, i) => {
    const teamRow = result.data.find(r => r.participant_id === teamId);
    return {
      round: rounds[i],
      position: teamRow?.position ?? null,
      points: teamRow?.points ?? null
    };
  });
}

Advanced technique 2: Combining standings with fixtures for a match-day view

On a match day, show the current table alongside the day's fixtures so users can see what's at stake.

async function getMatchDayContext(leagueId, seasonId, date) {
  const [standings, fixtures] = await Promise.all([
    api.getLiveStandings(leagueId, { include: 'participant:name' }),
    api.getFixturesByDate(date, {
      filters: `fixtureLeagues:${leagueId}`,
      include: 'participants;scores'
    })
  ]);

  return {
    table: standings.data.sort((a, b) => a.position - b.position),
    todaysMatches: fixtures.data
  };
}

6. Common errors

401 Unauthorised

Cause: Missing or invalid api_token. Fix: Confirm the token is correct and present on every request. Find it at MySportmonks.

404 Not Found

Cause: The season_id or round_id does not exist or belongs to a league outside your subscription. Fix: Use GET All Seasons to verify the season ID, or check the ID Finder.

429 Too Many Requests

Cause: Too many requests within your hourly limit. Fix: Cache standings (they only change after each matchday). See the Rate Limiting guide.

Empty data array from live standings

Cause: The league has no active season, or no matches are currently being played. Fix: Fall back to GET Standings by Season ID using the currentSeason ID retrieved from the leagues endpoint.

See also

Prerequisites

• Authentication : Setting up API access

• Leagues and Seasons : Finding season IDs and league IDs

• Includes : Enriching responses with team and stat data

Related data

• Fixtures : Show the fixtures that produced the current table

• Team Statistics : Deeper per-team performance metrics

• Topscorer Standings : Player rankings alongside the team table

• Expected Goals (xG) : xPTS alongside actual standings

• Season Schedule : Combine tables with round and stage data

Optimisation

• Filter and Select Fields : Narrow standings data

• Rate Limiting : Standings change per matchday; cache accordingly

Related endpoints

• Standings Endpoints : Complete API endpoint reference

• Rounds Endpoints : Retrieve round IDs for a season

FAQ

Q: How do I find the season ID for a league?

Use the leagues endpoint with include=currentSeason to get the active season ID, or include=seasons for all historical seasons. See the Leagues tutorial.

Q: How often are standings updated?

Standings update after each processed match. During an active match day, they reflect completed fixtures only. Use GET Live Standings to see in-progress positions.

Q: How do I handle leagues with group stages, like the UEFA Champions League?

Group-stage standings include a non-null group_id. Group results into separate tables by group_id before rendering.

Q: What does result: "equal" mean on a standing row?

It means the team's position did not change since the last update. "up" means they gained positions; "down" means they dropped.

Q: Are standings available on all plans?

Yes. All plans include standings access for their covered leagues.

Best practices summary

✅ DO:

• Use GET Standings by Season ID as your primary standings endpoint

• Use select on includes to return only the fields you need

• Cache standings, they only change after each matchday

• Retrieve types once from the Types endpoint and cache them rather than including .type

• Handle group_id to support cup competitions and group stages

❌ DON'T:

• Use GET All Standings, always scope to a season or round

• Include .type in production requests

• Use live standings for historical or completed seasons

• Assume all leagues have a single-table format