Skip to main content

​
Base URL

Season IDs must be discovered dynamically. Always call /api/tournaments/{id}/seasons first to get the numeric seasonId. The human-readable name field — "24/25" for European leagues or "2024" for calendar-year leagues like MLS and Brazilian Série A — is for display only and is not a valid URL parameter. See the Season IDs guide for full examples.

​
Seasons

​
Get Tournament Seasons

Returns all available seasons for a tournament. Call this first to discover valid seasonId values for other endpoints.
​
number
required
Numeric tournament ID. Use /api/search?q=premier+league or /api/leagues to discover.
Season name vs id — only the id is valid in downstream URLs. Sample response:
Pass 61627 (not "24/25") and 61644 (not "2024") to every /season/{seasonId}/... endpoint. See Season IDs for split-year vs calendar-year worked examples.

​
Standings

​
Overall Standings

Returns the full league table with points, wins, draws, losses, goals for/against, and goal difference.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/standings (lists trimmed to 2 items).

​
Home Standings

Returns standings based on home matches only.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/standings/home (lists trimmed to 2 items).

​
Away Standings

Returns standings based on away matches only.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/standings/away (lists trimmed to 2 items).

​
Statistics & Rankings

​
Top Players (competition leaders)

Returns data.topPlayers, an object keyed by statistic category. Each category holds up to 50 entries, each with the player, their team-season statistics value and appearances, and a playedEnough flag. This is the fastest way to get competition leaders — one request covers every category. Verified on 4 Sep 2026 for Premier League (17), Bundesliga (35) and Eredivisie (37): 30-32 categories per season, including rating, goals, expectedGoals, assists, expectedAssists, goalsAssistsSum, totalShots, shotsOnTarget, bigChancesCreated, bigChancesMissed, accuratePasses, keyPasses, accurateLongBalls, successfulDribbles, tackles, interceptions, clearances, possessionLost, penaltyGoals, penaltyWon, freeKickGoal, scoringFrequency, topSpeed, yellowCards, redCards, saves, goalsPrevented, cleanSheet, mostConceded and leastConceded.
​
string
default:"overall"
Match location filter. Only overall is currently served; home and away return 404 or 503 even though player-statistics/types advertises them. Omitting the parameter is equivalent to overall.
Category depth follows competition tier. Tier 1-3 seasons return the full set; Regionalliga seasons (42, 1085) return only goals; Oberliga Baden-Württemberg (142) returns 404. See Coverage for the tier table.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/top-players?type=overall (lists trimmed to 2 items).

​
Top Teams

Returns top-performing teams by various metrics.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/top-teams?type=overall (lists trimmed to 2 items).

​
Top Ratings

Returns player ratings leaderboard for the season.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/top-ratings?type=overall (lists trimmed to 2 items).

​
Season Player Index

Returns data.results — an index of { player, team } pairs for the season, plus page and pages. It does not contain statistic values.
Pagination on this endpoint is currently broken: page, limit, offset, order, accumulation, group and filters are all ignored, so only the first 10 entries are reachable even when pages reports 54. We are fixing it. Until then, build a full per-player season table from /api/tournament/{id}/season/{seasonId}/statistics/info (team list) plus /api/teams/{teamId}/players, then call /api/players/{playerId}/tournament/{id}/season/{seasonId}/statisticsper player. For leaderboards, use top-players instead.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/statistics (lists trimmed to 2 items).

​
Statistics Info

Returns the metadata needed to build a season stats UI:
  • teams — every team in the season (21 for Eredivisie 25/26)
  • statisticsGroups — category lists per group: summary, attack, defence, passing, goalkeeper, plus a detailed object with the expanded set per group
  • nationalities — nationalities represented in the season (61 for Eredivisie 25/26)
  • hideHomeAndAway — whether home/away splits should be offered in the UI
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/statistics/info (lists trimmed to 2 items).

​
Player Statistics Types

Returns data.types — currently ["overall", "home", "away"]. Note that only overall is served by the leaderboard and per-player season endpoints today.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/player-statistics/types (lists trimmed to 2 items).

​
Team Statistics Types

Returns available team statistic categories.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/team-statistics/types (lists trimmed to 2 items).

​
Player of the Season

Returns the player of the season award details, including nominees and winner.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/player-of-the-season (lists trimmed to 2 items).

​
Rounds & Events

​
All Rounds

Returns all matchday rounds for the season with round numbers and status.
League-format only. Some competitions (e.g. MLS, Brazilian Série A, and other regular-season/playoff leagues) do not expose traditional matchday rounds and will return a 404 here. Use /standings plus /events/last/{page} and /events/next/{page} for those tournaments instead.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/rounds (lists trimmed to 2 items).

​
Round Matches

Returns all matches in a specific round/matchday.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/round/1 (lists trimmed to 2 items).

​
Events by Round

Returns detailed event data for a specific round. This is the authoritative way to retrieve a complete Match Week — see Match Week and fixture ordering.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/events/round/1 (lists trimmed to 2 items).

​
Events by Round & Slug

Returns events filtered by round and slug identifier.
Cup rounds can require this slug form even when /rounds reports the numeric round. For example, a final listed as { "round": 29, "slug": "final" } may return 404 from /events/round/29 but succeed at /events/round/29/slug/final. Round responses can also omit venue when the full GET /api/match/{matchId} response contains it, so hydrate match details before marking a final’s stadium as unavailable.

​
Match Week and fixture ordering

Verified 12 Sep 2026 on Premier League (tournament 17), seasons 96668 (26/27) and 76986 (25/26).

​
The Match Week field

Every event object carries roundInfo, on both completed and upcoming fixtures. In league competitions it holds a single numeric round:
Cup and multi-stage competitions add name, slug and sometimes prefix, for example {"round":29,"name":"Final","slug":"final"} or {"round":636,"name":"Playoff round","slug":"playoff-round","prefix":"Qualification"}. GET /rounds returns the full round list plus the live currentRound:

​
Retrieving a complete Match Week

GET /api/tournament/17/season/96668/events/round/8 returned all 10 fixtures with teams, scores (homeScore.current / awayScore.current once played), status, startTimestamp, roundInfo, season, tournament and changes.changeTimestamp. Historical Match Weeks use the same route with an older seasonId from GET /api/tournaments/{id}/seasons.

​
There is no fixture-position field

The API does not publish a fixture number, sequence or position within a Match Week. There is no position, matchNumber or order field on any event object, and none is planned as an authoritative value.
The returned array is ordered by startTimestamp ascending, with same-kickoff fixtures grouped together; repeat calls returned identical ordering. Treat that as convenience, not a contract. If your application needs a stable fixture position, derive it once and persist it:
  1. Fetch the round.
  2. Sort by startTimestamp ascending, tie-breaking on homeTeam.id ascending (a stable numeric key, unlike names or array order).
  3. Assign your own 1..N index and store it against the event.id.
Because the position is now keyed to a fixture id in your own storage, later kickoff-time changes will not renumber your Match Week.

​
Postponed and rescheduled fixtures

A postponed fixture keeps its roundInfo.round and its original startTimestamp, and takes status.code 60 (postponed). The replay is published as a separate event id with the new kickoff and the same round. Verified example, Premier League 25/26 round 31: That round therefore returns 11 events rather than 10, and there is no field linking the replacement event back to the postponed one. Recommended handling: keep the postponed event at its original derived position, and append the replacement at the end of the round rather than renumbering. Match the pair on roundInfo.round plus homeTeam.id / awayTeam.id if you need to collapse them into one logical fixture.

​
Authoritative source per field

​
Last Events (Paginated)

Returns recent completed matches in the tournament, paginated. Page 0 returns the most recent.
​
number
required
Page number (0-indexed). Start with 0 for the most recent events.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/events/last/0 (lists trimmed to 2 items).

​
Next Events (Paginated)

Returns upcoming scheduled matches in the tournament season, paginated (30 per page). Page 0 returns the soonest upcoming events.
​
number
required
Page number (0-indexed). Start with 0 for the next batch of upcoming events.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/events/next/0 (lists trimmed to 2 items).

​
Season Teams

Returns all teams participating in a given season — useful for cup competitions and qualifying tournaments where the entrant list varies year to year.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/teams (lists trimmed to 2 items).

​
Brackets & Cup Tournaments

​
Knockout / Cup Tree

Returns the bracket/knockout tree for cup tournaments (e.g., FA Cup, Champions League). Includes all rounds from Round of 32 to the Final.
No example: this endpoint returned HTTP 404 for our Bundesliga sample on 24 September 2026. It only returns data when the entity has it (for example knockout draws, penalties or media), so handle an empty or 404 response.

​
Draw / Bracket (Alias)

Alias for the knockout endpoint — returns the same bracket/draw data.
Only available for cup/knockout tournaments. League tournaments will return empty data.
No example: this endpoint returned HTTP 404 for our Bundesliga sample on 24 September 2026. It only returns data when the entity has it (for example knockout draws, penalties or media), so handle an empty or 404 response.

​
Team of the Week

​
Available Periods

Returns available Team of the Week periods (matchdays). Use the returned periodId values to fetch specific team-of-the-week selections.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/team-of-the-week/periods (lists trimmed to 2 items).

​
Team of the Week by Period

Returns the best XI for a specific matchday period, including formation, player ratings, and key stats.
​
number
required
Period ID from the /team-of-the-week/periods endpoint.

​
Team Performance

​
Team Performance Graph

Returns a team’s performance trajectory over the season — position changes after each matchday.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/team/2561/performance-graph (lists trimmed to 2 items).

​
Team Events

Returns all events for teams in the tournament season.
​
string
default:"total"
Filter: total, home, or away.
No example: this endpoint returned HTTP 404 for our Bundesliga sample on 24 September 2026. It only returns data when the entity has it (for example knockout draws, penalties or media), so handle an empty or 404 response.

​
Tournament Info

​
Tournament Details

Returns competition metadata: name, category and country, logo, tier, title holder, upper and lower divisions, and startDateTimestamp / endDateTimestamp.
No current-season field. This response does not contain a currentSeason object. To resolve the season in progress, call GET /api/tournaments/{tournamentId}/seasons — the list is newest first, so seasons[0] is the current season.Two caveats when you do that (verified 3 September 2026):
  • Amateur and regional tiers can legitimately still have 25/26 on top. Upstream only opens a season once fixtures are published for it, so competitions such as the Dutch 1e/2e Klasse divisions (28689-28699, 21252) and German Kreis-level competitions had not yet rolled over to 26/27, while every senior competition checked had.
  • year is not always XX/YY. Calendar-year competitions return values like 2026, and some return labels such as Season 3. Compare by season id or by the season’s date range rather than parsing the year string.
Recorded 24 September 2026 from GET /v2/football/tournament/35/info (lists trimmed to 2 items).

​
Season Info

Returns season-specific information: start/end dates, number of teams, current round.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/info (lists trimmed to 2 items).
Returns highlighted/featured matches for the tournament (e.g., derbies, title deciders).
Recorded 24 September 2026 from GET /v2/football/tournament/35/featured-events (lists trimmed to 2 items).

​
Tournament Image

Returns the tournament logo/badge image URL.
Recorded 24 September 2026 from GET /v2/football/tournament/35/image (lists trimmed to 2 items).

​
Tournament Media

Returns media content (photos, videos) for the tournament.
Not all tournaments have media content. Top-tier leagues are more likely to have media available.
Recorded 24 September 2026 from GET /v2/football/tournament/35/media (lists trimmed to 2 items).

​
Venues

Returns all venues used in the tournament season, with capacity, location, and coordinates.
Available only for competitions that also carry event-level venue data (verified down to 3. Liga, ID 491). For Regionalliga, Oberliga and lower tiers this endpoint returns 404 — resolve the home club’s ground instead, as described in Venue availability by competition tier.
Recorded 24 September 2026 from GET /v2/football/tournament/35/season/97464/venues (lists trimmed to 2 items).

​
Scheduled Events by Date

Returns all events for this tournament on a specific date.
​
string
required
Date in YYYY-MM-DD format (e.g., 2025-03-15).
Recorded 24 September 2026 from GET /v2/football/tournament/35/scheduled-events/2026-09-20 (lists trimmed to 2 items).

​
Example Requests

​
Example responses

Real responses recorded on 24 September 2026 from the Bundesliga (tournament 35, season 97464), match SC Paderborn 07 3-1 TSG Hoffenheim (16434052). Long lists are shortened to the first items; field names and structure are unchanged.
Last modified on September 24, 2026