Leagues and seasons

This guide covers how leagues and seasons are structured in the Motorsport API, how to retrieve them, and how to use them to navigate to the rest of the data hierarchy.

When to use this

Use leagues and seasons when you want to:

Find the league ID and current season ID before making other requests
Build a season selector for a race calendar or standings page
Check whether a season is current, pending, or finished
Retrieve all seasons for a given championship

The hierarchy

League (championship)
  └── Season (calendar year)
        └── Stage (race weekend)
              └── Fixture (individual session)

A League is the championship, for example the Formula 1 World Championship. A Season is a calendar year within that championship. Most other requests in the API require a season_id or league_id, so retrieving these first is the usual starting point.

Retrieving leagues

Get all leagues in your subscription:

GET https://api.sportmonks.com/v3/motorsport/leagues
?api_token={your_token}

A league response looks like this:

{
  "data": [
    {
      "id": 3468,
      "sport_id": 2,
      "country_id": 462,
      "name": "Formula 1",
      "active": 1,
      "short_code": "F1",
      "image_path": "https://cdn.sportmonks.com/images/motorsport/leagues/3468.png",
      "type": "formula_one",
      "sub_type": "formula_one",
      "last_played_at": "2025-12-07 13:00:00",
      "category": 1,
      "has_jerseys": false
    }
  ]
}

To get the current season alongside the league in one call:

GET https://api.sportmonks.com/v3/motorsport/leagues
?api_token={your_token}&include=currentSeason

Retrieving seasons

Get all seasons for a specific league using the seasonLeagues filter:

GET https://api.sportmonks.com/v3/motorsport/seasons
?api_token={your_token}&filters=seasonLeagues:3468

A season response looks like this:

{
  "data": [
    {
      "id": 25273,
      "sport_id": 2,
      "league_id": 3468,
      "name": "2025",
      "finished": 0,
      "pending": 0,
      "is_current": 1,
      "starting_at": "2025-03-14",
      "ending_at": "2025-12-07",
      "standings_recalculated_at": "2025-11-23 19:15:31"
    }
  ]
}

is_current indicates the active season. finished and pending let you determine whether a season is complete or yet to begin.

To get the current season only, filter for is_current after fetching the list, or use the currentSeason include on the league:

GET https://api.sportmonks.com/v3/motorsport/leagues/3468
?api_token={your_token}&include=currentSeason

Working with the data

Find the current season ID

const API_TOKEN = 'your_token';

async function getCurrentSeasonId(leagueId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/seasons?api_token=${API_TOKEN}&filters=seasonLeagues:${leagueId}`
  );
  const { data } = await response.json();
  const current = data.find(s => s.is_current === 1);
  return current?.id ?? null;
}

import requests

API_TOKEN = "your_token"

def get_current_season(league_id):
    url = "https://api.sportmonks.com/v3/motorsport/seasons"
    params = {
        "api_token": API_TOKEN,
        "filters": f"seasonLeagues:{league_id}"
    }
    response = requests.get(url, params=params)
    seasons = response.json()["data"]
    current = next((s for s in seasons if s["is_current"] == 1), None)
    return current["id"] if current else None

season_id = get_current_season(3468)

<?php
function getCurrentSeasonId(string $apiToken, int $leagueId): ?int {
    $url = "https://api.sportmonks.com/v3/motorsport/seasons?api_token={$apiToken}&filters=seasonLeagues:{$leagueId}";
    $response = json_decode(file_get_contents($url), true);
    foreach ($response['data'] as $season) {
        if ($season['is_current'] === 1) {
            return $season['id'];
        }
    }
    return null;
}

Build a season selector

async function getAllSeasons(leagueId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/seasons?api_token=${API_TOKEN}&filters=seasonLeagues:${leagueId}&order=desc`
  );
  const { data } = await response.json();
  return data.map(s => ({ id: s.id, name: s.name, isCurrent: s.is_current === 1 }));
}

def get_all_seasons(league_id):
    url = "https://api.sportmonks.com/v3/motorsport/seasons"
    params = {
        "api_token": API_TOKEN,
        "filters": f"seasonLeagues:{league_id}",
        "order": "desc"
    }
    response = requests.get(url, params=params)
    return [
        {"id": s["id"], "name": s["name"], "is_current": s["is_current"]}
        for s in response.json()["data"]
    ]

<?php
const API_TOKEN = 'YOUR_TOKEN';
function get_all_seasons($leagueId) {
    $url = "https://api.sportmonks.com/v3/motorsport/seasons";
    $params = [
        "api_token" => API_TOKEN,
        "filters" => "seasonLeagues:" . $leagueId,
        "order" => "desc"
    ];
    $requestUrl = $url . "?" . http_build_query($params);
    $response = file_get_contents($requestUrl);
    if ($response === false) {
        return [];
    }
    $json = json_decode($response, true);
    $data = $json["data"] ?? [];
    return array_map(function ($season) {
        return [
            "id" => $season["id"] ?? null,
            "name" => $season["name"] ?? null,
            "isCurrent" => isset($season["is_current"]) && $season["is_current"] === 1
        ];
    }, $data);
}

Common pitfalls

Using league_id where season_id is required. Most data endpoints (fixtures, standings, stages) filter by season_id, not league_id. Always resolve the current season_id first rather than passing the league ID to a downstream request.

Assuming is_current returns a boolean. The is_current field returns an integer: 1 for the current season, 0 otherwise. Use === 1 rather than a truthy check in strictly typed code.

Not paginating the seasons list. A championship with many years of history can have more seasons than the default page size. Use cursor-based pagination to retrieve the full list. See Pagination.

tie_breaker_rule_id and games_in_current_week are not used in the Motorsport API. These fields exist on the Season entity for cross-sport compatibility but are not applicable to motorsport data. Treat them as null.

Common errors

Status

Likely cause

401

Missing or invalid api_token

404

The league or season ID does not exist in your subscription

FAQ

What is the Formula 1 league ID? The league ID for Formula 1 is 3468, as shown in the example response above. You can confirm this by calling GET /motorsport/leagues with your token.

How do I get the season ID for a specific year? Filter seasons by league, then match on the name field which contains the calendar year (e.g. "2025").

Is there always exactly one current season? In practice yes, but defensively code for the possibility of zero results from the is_current filter in case the season transition has not yet been applied on Sportmonks' side.

What does standings_recalculated_at mean? It is the timestamp of the last standings recalculation for that season. Useful for knowing whether standings data is fresh after a race weekend.

Last updated 11 days ago

Was this helpful?