Leaderboards, Head-to-Head & Venues

GET /leaderboards

Returns the top players ranked by any basic stat column, ordered descending. Ideal for "who had the most goals in round X?" style queries.

Query Parameters

Name	Type	Required	Description
stat	string	Yes	Stat to rank by (see valid values below)
year	integer	No	Filter by season year
round	integer	No	Filter by round
team_id	string	No	Filter to a single team's players
limit	integer	No	Default 50, max 200
offset	integer	No	Default 0

Valid stat values

kicks, handballs, disposals, marks, goals, behinds, tackles, hitouts,
goal_assists, inside_50s, clearances, clangers, rebound_50s,
frees_for, frees_against, afl_fantasy_pts, supercoach_pts

Examples

# Top 10 disposal getters in 2024
GET /leaderboards?stat=disposals&year=2024&limit=10

# Highest goal tallies in round 5 for Sydney
GET /leaderboards?stat=goals&year=2024&round=5&team_id=sydney

Response

{
  "data": [
    { "playerId": 144, "playerName": "Chad Warner", "teamId": "sydney", "value": 32 },
    { "playerId": 201, "playerName": "Marcus Bontempelli", "teamId": "western-bulldogs", "value": 31 }
  ],
  "meta": { "limit": 10, "offset": 0, "count": 10, "total": 4820 }
}

GET /head-to-head

Returns the match history between two teams, regardless of which was home or away.

Query Parameters

Name	Type	Required	Description
team_a	string	Yes	First team slug
team_b	string	Yes	Second team slug
year	integer	No	Filter to a specific season
venue	string	No	Filter to a specific venue
limit	integer	No	Default 50, max 200
offset	integer	No	Default 0

Example

# Swans vs Magpies all-time at the SCG
GET /head-to-head?team_a=sydney&team_b=collingwood&venue=SCG

Response is a standard paginated list of match objects (same shape as GET /matches).

GET /venues

Returns all venues in the database with match counts, ordered by most matches. Useful for getting valid venue values for the venue filter on other endpoints.

Response

{
  "data": [
    { "venue": "MCG", "matchCount": 412 },
    { "venue": "Marvel Stadium", "matchCount": 298 },
    { "venue": "SCG", "matchCount": 186 }
  ],
  "meta": { "count": 24 }
}