Season IDs

How to resolve numeric seasonId values for both split-year (24/25) and calendar-year (2024) leagues. Avoid 404s on historical data lookups.

The two-step workflow

Every season-scoped Football V2 endpoint takes a numeric seasonId — never a year string. Human-readable labels like "24/25" or "2024" are display names returned in the name and year fields. They are not valid URL parameters.

Resolve the ID first, then use it everywhere else:

1. GET /api/tournaments/{tournamentId}/seasons
      └─> returns [{ id: 61644, name: "2024", year: "2024" }, ...]

2. GET /api/tournament/{tournamentId}/season/{seasonId}/...
      └─> use the numeric `id` from step 1

GET /api/tournament/242/matches/2024 returns 404. There is no /matches/{year} shortcut. The path season/{seasonId} is the only correct form.

---

Why the label format varies

Different leagues run on different calendars, so the upstream name field reflects the real-world season:

League type	Example leagues	name format	Example
Split-year (Aug → May)	Premier League, La Liga, Serie A, Bundesliga, UCL	YY/YY	"24/25"
Calendar-year (Mar → Dec)	MLS, Brazilian Série A, J1 League, Argentine Primera	YYYY	"2024"

The id field is always numeric and always the right value to pass downstream. The format of name only matters when you want to display the season to a human user.

---

Worked example: split-year league (Premier League)

uniqueTournament.id = 17

cURL

# Step 1 — list seasons
curl https://api.sportsapipro.com/v2/football/tournaments/17/seasons \
  -H "x-api-key: YOUR_API_KEY"

# Response (trimmed):
# { "seasons": [
#     { "id": 61627, "name": "24/25", "year": "24/25" },
#     { "id": 52186, "name": "23/24", "year": "23/24" }
# ] }

# Step 2 — fetch matches using the numeric id
curl https://api.sportsapipro.com/v2/football/tournament/17/season/61627/events/last/0 \
  -H "x-api-key: YOUR_API_KEY"

const headers = { 'x-api-key': 'YOUR_API_KEY' };
const base = 'https://api.sportsapipro.com/v2/football';

const { seasons } = await fetch(
  `${base}/api/tournaments/17/seasons`,
  { headers }
).then(r => r.json());

const current = seasons[0]; // most recent
const matches = await fetch(
  `${base}/api/tournament/17/season/${current.id}/events/last/0`,
  { headers }
).then(r => r.json());

import requests

H = {"x-api-key": "YOUR_API_KEY"}
BASE = "https://api.sportsapipro.com/v2/football"

seasons = requests.get(f"{BASE}/api/tournaments/17/seasons", headers=H).json()["seasons"]
current = seasons[0]
matches = requests.get(
    f"{BASE}/api/tournament/17/season/{current['id']}/events/last/0",
    headers=H,
).json()

---

Worked example: calendar-year league (MLS)

uniqueTournament.id = 242

The flow is identical — only the season name differs:

# Step 1
curl https://api.sportsapipro.com/v2/football/tournaments/242/seasons \
  -H "x-api-key: YOUR_API_KEY"

# Response (trimmed):
# { "seasons": [
#     { "id": 61644, "name": "2024", "year": "2024" },
#     { "id": 52345, "name": "2023", "year": "2023" }
# ] }

# Step 2 — use the numeric id, NOT "2024"
curl https://api.sportsapipro.com/v2/football/tournament/242/season/61644/standings \
  -H "x-api-key: YOUR_API_KEY"

curl https://api.sportsapipro.com/v2/football/tournament/242/season/61644/events/round/1 \
  -H "x-api-key: YOUR_API_KEY"

/api/tournament/242/matches/2024 and /api/tournament/242/season/2024/... both return 404. Always pass the numeric id (61644), never the year string.

---

Recipe: fetch a full season of historical matches

Combine seasons → rounds → events to walk an entire competition:

const headers = { 'x-api-key': 'YOUR_API_KEY' };
const base = 'https://api.sportsapipro.com/v2/football';
const tournamentId = 17;

// 1. Resolve season
const { seasons } = await fetch(
  `${base}/api/tournaments/${tournamentId}/seasons`, { headers }
).then(r => r.json());
const seasonId = seasons[0].id;

// 2. Discover rounds for that season
const { rounds } = await fetch(
  `${base}/api/tournament/${tournamentId}/season/${seasonId}/rounds`, { headers }
).then(r => r.json());

// 3. Fetch each round's events
const allMatches = [];
for (const r of rounds) {
  const { events } = await fetch(
    `${base}/api/tournament/${tournamentId}/season/${seasonId}/events/round/${r.round}`,
    { headers }
  ).then(res => res.json());
  allMatches.push(...events);
}

The same shape works for calendar-year leagues — only tournamentId and the resulting seasonId change.

---

Caching the resolution step

/seasons is a low-volatility endpoint — the active season changes at most a few times per year. Cache the response client-side (24h TTL is safe) so you only pay the discovery cost once per league per day.

const seasonCache = new Map(); // tournamentId -> { id, expiresAt }

async function currentSeasonId(tournamentId) {
  const hit = seasonCache.get(tournamentId);
  if (hit && hit.expiresAt > Date.now()) return hit.id;

  const { seasons } = await fetch(
    `${base}/api/tournaments/${tournamentId}/seasons`, { headers }
  ).then(r => r.json());

  const id = seasons[0].id;
  seasonCache.set(tournamentId, { id, expiresAt: Date.now() + 86_400_000 });
  return id;
}

---

Related

• Canonical IDs — uniqueTournament.id (store this) vs tournament.id (per-season variant)
• Tournament Endpoints — full list of season-scoped routes
• Troubleshooting — common 404 patterns