Skip to main content

API Authentication Update - M2M accounts

ยท One min read
Nick Eggleton

Ahead of the 2025 season we are updating the AFL API's authentication module as part of a review to improve our support processes.

As part of this update, if you are using an M2M account to communicate with the AFL API, the account's credentials (the Client ID and Client Secret) will be refreshed. This requires action on your part to ensure your applications continue to have access to the AFL API.

note

AFL API User Accounts are not affected by this update - no changes are required.

What needs updating?โ€‹

Once you have received your new Client Id & Secret (via a secure link sent by email), replace the existing values with the new ones.

In addition, the M2M token address has changed - update it to the following:

New M2M token request URL
https://championdata-afl.au.auth0.com/oauth/token

When can I apply these changes?โ€‹

As soon as you receive them from Champion Data - they take immediate effect.

How long do I have to make the change?โ€‹

The original M2M credentials will be deactivated week commencing 10th March 2025, after the season has started.

Questions?โ€‹

Please email your questions to support@championdata.com.au.

2024 Season Roundup

ยท 6 min read
Nick Eggleton

With the AFL Premiership season done, and AFLW 2024 approaching the finish line, we thought it would be a good point to summarise everything added to the AFL API this year.

New API Featuresโ€‹

Match Statistic POST endpointsโ€‹

At the start of the year, we introduced the Match Statistics POST Endpoints. While they perform the same function as the GET Endpoints, they enable you to make multiple statistic queries against a match in one API call, rather than several. They are both faster and more efficient, plus they save on API calls when you're watching your usage limit.

AFLW Matchesโ€‹

AFLW is now formally supported by the AFL API, providing both past, live and future matches as they happen. AFLW matches work near identically to their Premiership counterparts, so you can reuse existing reports, dashboards and applications for AFLW simply by querying their match ids.

'Last X' match statistics filterโ€‹

The match statistics endpoints can now be filtered to a time range within a period, or to the last few minutes of play in a period. This can be used to drive a match day dashboard that shows how players are doing for the past 10 minutes.

Match Transaction & Summary File Support Package Functionsโ€‹

The R Package (and later this year, the Python Package) now provides functions to generate these support site files from the AFL API.

New Metricsโ€‹

The following metrics were added to the AFL API between March and October this year.

  • ABSENCE_CENTRE_BOUNCE_LOSS_PCT

    The percentage of a players total centre bounce absences that result in a clearance to the opposition squad.

  • ABSENCE_CENTRE_BOUNCE_NEUTRAL_PCT

    The percentage of a players total centre bounce absences that do not result in a clearance for that centre bounce for either team.

  • ABSENCE_CENTRE_BOUNCE_WIN_PCT

    The percentage of a players total centre bounce absences that result in a clearance to the given players squad.

  • ATTENDANCE_CENTRE_BOUNCE_LOSS_PCT

    The percentage of a players total centre bounce attendances that result in a clearance to the opposition squad.

  • ATTENDANCE_CENTRE_BOUNCE_NEUTRAL_PCT

    The percentage of a players total centre bounce attendances that do not result in a clearance for that centre bounce for either team.

  • ATTENDANCE_CENTRE_BOUNCE_WIN_PCT

    The percentage of a players total centre bounce attendances that result in a clearance to the given players squad.

  • CLEARANCE_PCT

    The percentage of all stoppages that resulted in a clearance win.

  • DISPOSAL_PER_TURNOVER

    Ratio of Disposals compared to Disposals that were also turnovers.

  • DISPOSAL_TURNOVER

    Disposals that resulted in a turnover, where the zone is attributed to the zone of the disposal.

  • GOAL_EXPECTED

    Total goals expected from a given shot (based on location, pressure, sidedness). At a transaction level this will show expected accuracy and when summed will show the expected goal.

  • HANDBALL_TURNOVER

    Handballs that resulted in a turnover, where the zone is attributed to the zone of the handball.

  • INSIDE_50_FORCED_ENTRY_RETURN

    Total points returned after a forced inside 50 entry and before another inside 50 or centre bounce.

  • INSIDE_50_INITIAL_DIRECT_ENTRY_RETURN

    Total points returned after a direct initial inside 50 entry and before another inside 50 or centre bounce.

  • INSIDE_50_INITIAL_ENTRY_RETURN

    Total points returned after an initial inside 50 entry and before another inside 50 or centre bounce.

  • INSIDE_50_MID_STOPPAGE_DIRECT_ENTRY_RETURN

    Total points returned after a direct midfield stoppage inside 50 entry and before another inside 50 or centre bounce.

  • INSIDE_50_MID_STOPPAGE_ENTRY_RETURN

    Total points returned after a midfield stoppage inside 50 entry and before another inside 50 or centre bounce.

  • INSIDE_50_REPEAT_DIRECT_ENTRY_RETURN

    Total points returned after a direct repeat inside 50 entry and before another inside 50 or centre bounce.

  • INSIDE_50_REPEAT_ENTRY_RETURN

    Total points returned after a repeat inside 50 entry and before another inside 50 or centre bounce.

  • INSIDE_50_TRANSITION_DIRECT_ENTRY_RETURN

    Total points returned after a direct transition inside 50 entry and before another inside 50 or centre bounce.

  • INSIDE_50_TRANSITION_ENTRY_RETURN

    Total points returned after a transition inside 50 entry and before another inside 50 or centre bounce.

  • KICK_TURNOVER

    Kicks that resulted in a turnover, where the zone is attributed to the zone of the kick.

  • METRES_GAINED_ASSISTED

    Total metres gained by a teammate that receives an uncontested possession from your disposal.

  • METRES_GAINED_DISPOSAL

    Metres Gained via disposals. Measured from the point the original point of possession to the next possession or stoppage.

  • METRES_GAINED_DISPOSAL_AVG

    The average number of meters gained per-disposal

  • METRES_GAINED_HANDBALL

    Metres Gained via handballs. Measured from the point the original point of possession to the next possession or stoppage.

  • METRES_GAINED_HANDBALL_AVG

    The average number of meters gained via handballs

  • METRES_GAINED_KICK

    Metres Gained via kicks, measured from the point of the original possession to the next possession or stoppage.

  • METRES_GAINED_KICK_AVG

    The average number of metres gained via kicks

  • METRES_GAINED_NET

    Metres Gained plus Assisted Metres Gained.

  • METRES_GAINED_OTHER

    Metres Gained not via disposals.

  • METRES_GAINED_RETAIN

    Metres Gained where the disposal/possession was retained.

  • ONE_PERCENTER

    Cumulation of knock ons, shepherds, credits, spoils and smothers.

  • POINTS_ABOVE_EXPECTED

    Total points scored above the expected score.

  • POSSESSION_CONTESTED_PCT

    The percentage of all possessions that are contested possessions.

  • POSSESSION_UNCONTESTED_PCT

    The percentage of all possessions that are uncontested possessions.

  • PRESSURE_ACT_FORCED_TURNOVER_BEHI_PCT

    The percentage of all forced turnovers that result in a behind.

  • PRESSURE_ACT_FORCED_TURNOVER_GOAL_PCT

    The percentage of all forced turnovers that result in a goal.

  • PRESSURE_ACT_FORCED_TURNOVER_POINTS

    Total points generated by pressure acts forcing a turnover.

  • PRESSURE_ACT_FORCED_TURNOVER_SCORE_PCT

    The percentage of all forced turnovers that result in a score.

  • RANKING_POINTS

    The Official Champion Data AFL Rankings system was established in 1999 and has been developed into a robust and comprehensive system for objectively measuring player performance through the use of statistical measures. The rankings are geared to reward the winning factors of a game of AFL football. They are used as the scoring measure in the Herald-Sun SuperCoach fantasy game.

  • TIME_IN_POSSESSION_DISPUTE_PCT

    The percentage of total elapsed time where the ball was in play but neither team had possession.

  • TIME_ON_GROUND_LOOSE

    Time in seconds that a player was loose during a game.

  • TIME_ON_GROUND_LOOSE_PCT

    Percentage of time that a player was loose during a game.

How It Works - AFLW in the API

ยท 2 min read
Nick Eggleton

The complete 2023 season of the NAB AFLW league is now available from the AFL API. This article describes how you can access AFLW 2023 matches and what API endpoints apply to them.

info

You must be licensed to access the AFLW league and its matches. If it isn't returned by the Leagues endpoint as described below, please contact Champion Data to check if you are correctly licensed.

AFLW Leagueโ€‹

The AFLW League has been assigned league Id 3, which you can see here when you call the Leagues endpoint.

Leagues

You can call every Season endpoint using league Id 3, they all support AFLW. Currently only the 2023 and (upcoming) 2024 seasons are available from the API, so you will receive a 404 error if you call on the prior seasons.

AFLW Matchesโ€‹

AFLW match data is accessed the same way as AFL Premiership matches; by looking up their match ids and calling the match endpoints.

As with the AFL Premiership, you can look up AFLW matches via the Season Fixture endpoint (enter league Id 3, level Id 1, season 2023) and get their match ids from there.

AFLW matches are supported by all the match endpoints, including the transactions endpoint if you are licensed to access it.

Sandbox AFLW Match Replayโ€‹

The Sandbox environment contains a replaying AFLW match, starting at the same times as the other matches. Note however, as AFLW match quarters are shorter than Premiership matches, the match status timing table doesn't completely align with the AFLW match.

Unsupported Metricsโ€‹

The following metrics do not support AFLW matches and are not returned via the match statistic endpoints.

GroupMetrics
Player Ratings
  • PLAYER_RATING
  • PLAYER_RATING_BALL_USE
  • PLAYER_RATING_BALL_USE_FIELD_KICK
  • PLAYER_RATING_BALL_USE_HANDBALL
  • PLAYER_RATING_BALL_USE_KICK_IN
  • PLAYER_RATING_BALL_USE_SHOT_AT_GOAL
  • PLAYER_RATING_BALL_WINNING
  • PLAYER_RATING_BALL_WINNING_INTERCEPT
  • PLAYER_RATING_BALL_WINNING_MID_CHAIN
  • PLAYER_RATING_BALL_WINNING_STOPPAGE
  • PLAYER_RATING_DEFENCE
  • PLAYER_RATING_DEFENCE_PRESSURE
  • PLAYER_RATING_DEFENCE_SPOIL
  • PLAYER_RATING_HITOUT
  • PLAYER_RATING_NEGATIVE
  • PLAYER_RATING_NEGATIVE_50M_PENALTY
  • PLAYER_RATING_NEGATIVE_DEBIT
  • PLAYER_RATING_NEGATIVE_FREE_KICK_AGAINST
Expected Score
  • POINTS_EXPECTED
  • SHOT_AT_GOAL_ACCURACY_EXPECTED
Time on Ground
  • TIME_ON_GROUND_DEFENCE
  • TIME_ON_GROUND_DEFENCE_PCT
  • TIME_ON_GROUND_FORWARD
  • TIME_ON_GROUND_FORWARD_PCT
  • TIME_ON_GROUND_MATCHUPS
  • TIME_ON_GROUND_MIDFIELD
  • TIME_ON_GROUND_MIDFIELD_PCT
  • TIME_ON_GROUND_ON_BALL
  • TIME_ON_GROUND_ON_BALL_PCT
  • TIME_ON_GROUND_RUCK
  • TIME_ON_GROUND_RUCK_PCT
  • TIME_ON_GROUND_WING
  • TIME_ON_GROUND_WING_PCT

How It Works - Last 5/10 Minutes

ยท 2 min read
Nick Eggleton

GET Endpointsโ€‹

The match stat GET endpoints now provides a new filter parameter called "lastXSeconds". This parameters filters the stats so they only count transactions that occurred on or within the last 'X' seconds of the match.

If used on a live match and called periodically, the stats will go up and down based on what's happened in the last number of seconds. As it is a 'seconds' filter, enter 300 to filter the last 5 minutes, 600 for last 10.

From and To Period Secondsโ€‹

Two more parameters have been added to the endpoints alongside lastXSeconds: fromPeriodSeconds and toPeriodSeconds.

These can be used to filter statistics to a particular range of time within a quarter. They can be used independently of each other, where they will run from the start/end of the quarter, or together to focus on a mid-quarter window.

note

These parameters aren't used in Last 5/10 Minutes filtering, and described here for completeness. Also note that you cannot use all three parameters at the same time - the API will return an error message stating this is the case.

POST Endpointsโ€‹

The match stat POST endpoints also support these parameters, they can be supplied in each metic request, and in different combinations in each request. They perform the same filtering as they do for the GET Endpoints.

R Package Support

The R package's getPlayerStats and getSquadStats function also include 'lastXSeconds' parameters to be used in the same fashion as calling the API endpoints directly. It too supports using the parameters in the getPlayerStatsPOST and getSquadStatsPOST endpoints. See here for more details.

Work in Progress - Last 5/10 Minutes

ยท One min read
Nick Eggleton

Over the past few weeks, the team have been busily working on some new time parameters to the match statistics endpoints. They are intended to filter stats to what happened in a specific time period within a quarter, or to filter to the last few minutes of activity.

Match stat endpoint time parameters

fromPeriodSeconds and toPeriodSeconds can be used to analyse performance within a specific time period in a match, especially when used with a period filter so you can examine performance in the first 5 minutes of every priod.

If used on a live match (and without a period filter), lastXSeconds gets you the stats from say the last 5 or 10 minutes of play. Best used in concert with a metric filter to keep the endpoint response small and manageable.

These new parameters will be implemented on both GET and POST endpoints (illustrated here on GET) and on both squad and player stats endpoints. They will also be available via the R & Python API Support Packages.

info

Everything presented here is subject to change prior to release - we may add, remove or rename these parameters before we release.