Skip to main content

AFL API Python Package Documentation

Details​

Package: champion_data
Version: 1.1.1
Author: Champion Data
Maintainer: Aaron Brougham <aaron.brougham@championdata.com.au>, Minh Dinh.

Package Functions​

API Objects​

class API(object)

Set up the API connection info You can use either a username / password for basic auth, or alternative versions using client_id/client_secret for OAuth2 authentication.

Examples:

api_un: str = "username"
api_pw: str = "password"

api: champion_data.API = champion_data.API(
    username=api_un,
    password=api_pw,
    verbose=True,
)
api.current_season()

current_season​

def current_season(league_id: int = 1, level_id: int = 1, **kwargs) -> int

Get current season for a league and level.

Arguments:

  • league_id int, optional - A unique numerical identifier of a league. Defaults to 1 (AFL Men's Premiership).
  • level_id int, optional - A unique numerical identifier of a level. Defaults to 1 (Seniors).

Raises:

  • Exception - Error when fetching data.

Returns:

  • int - A numerical value for season ID.

Examples:

api.current_season()
api.current_season(league_id=1, level_id=1)

entries​

def entries(match_id: int, **kwargs) -> pandas.DataFrame

A data frame with a list of inside 50 entries for a match, with one row per entry. NULL if the match is yet to start.

Arguments:

  • match_id int - A unique numerical identifier of a match.

Returns:

  • pandas.DataFrame - A data frame with a list of inside 50 entries for a match, with one row per entry. NULL if the match is yet to start.
    • match_id : A unique numerical identifier of a match.
    • entry_trx_id : The transaction ID of the entry, used for ordering chronologically.
    • entry_period : The period of the entry.
    • entry_period_secs : The elapsed time within the period of the entry.
    • entry_player_id : A unique numerical identifier of the player responsible for the entry.
    • entry_player_fullname : The fullname of the player responsible for the entry.
    • entry_player_display_name : The display name of the player responsible for the entry.
    • entry_squad_id : A numerical identifier of the squad player responsible for the entry belongs to.
    • entry_squad_name : The name of the squad the player responsible for the entry belongs to.
    • entry_squad_code : A short code to represent the squad the player responsible for the entry belongs to.
    • entry_type : The type of inside 50 entry.
    • entry_result_outcome :
    • entry_source_name : The game situation relative to the origin of a team's possession that results in an entry.
    • entry_source_type : Inside 50 entries where direct indicates the first chain after the specified entry_source_name. For centre bounce and midfield stoppage entry_source_name, direct indicates the entry was in the clearance chain. For repeat entry_source_name, direct indicates the entry was on the first turnover chain after an opposition rebound 50. For transition entry_source_name, direct indicates the entry was in the same chain as the rebound 50.
    • entry_kick_is_ground : For inside 50 entries that are kicks, was the entry from a ground kick (true/false).
    • entry_kick_foot : For inside 50 entries that are kicks, which foot did the kicking player use.
    • entry_kick_intent : For inside 50 entries that are kicks, the intent of the kicker.
    • entry_kick_distance : For inside 50 entries that are kicks, the distance of the kick.
    • entry_kick_direction : For inside 50 entries that are kicks, the direction of the kick.
    • entry_kick_launch_distance_to_goal : For inside 50 entries that are kicks, the straight line distance to goal from the launch point of the kick.
    • entry_kick_result_distance_to_goal : For inside 50 entries that are kicks, the straight line distance to goal from the result point of the kick.
    • entry_kick_pressure_name : For inside 50 entries that are kicks, the name of the type of pressure applied to the kicker.
    • entry_kick_pressure_code : For inside 50 entries that are kicks, a short code to describe the type of pressure applied to the kicker.
    • entry_kick_pressure_points : For inside 50 entries that are kicks, the number of points associated with the pressure type applied to the kicker.
    • entry_kick_launch_location_x : The x coordinate of the inside 50 launch location.
    • entry_kick_launch_location_y : The y coordinate of the inside 50 launch location.
    • entry_kick_launch_location_x_std : The x coordinate of the inside 50 launch location transformed to a standard ground dimension (160x141).
    • entry_kick_launch_location_y_std : The y coordinate of the inside 50 launch location transformed to a standard ground dimension (160x141).
    • entry_kick_launch_location_rotated_x : The x coordinate of the inside 50 launch location rotated to give all squads attacking left-to-right.
    • entry_kick_launch_location_rotated_y : The y coordinate of the inside 50 launch location rotated to give all squads attacking left-to-right.
    • entry_kick_launch_location_rotated_x_std: The x coordinate of the inside 50 launch location transformed to a standard ground dimension (160x141) & rotated to give all squads attacking left-to-right.
    • entry_kick_launch_location_rotated_y_std: The x coordinate of the inside 50 launch location transformed to a standard ground dimension (160x141) & rotated to give all squads attacking left-to-right.
    • entry_kick_result_location_x : The x coordinate of the inside 50 result location.
    • entry_kcik_result_location_y : The y coordinate of the inside 50 result location.
    • entry_kick_result_location_x_std : The x coordinate of the inside 50 result location transformed to a standard ground dimension (160x141).
    • entry_kick_result_location_y_std : The y coordinate of the inside 50 result location transformed to a standard ground dimension (160x141).
    • entry_kick_result_location_rotated_x : The x coordinate of the inside 50 result location rotated to give all squads attacking left-to-right.
    • entry_kick_result_location_rotated_y : The y coordinate of the inside 50 result location rotated to give all squads attacking left-to-right.
    • entry_kick_result_location_rotated_x_std: The x coordinate of the inside 50 result location transformed to a standard ground dimension (160x141) & rotated to give all squads attacking left-to-right.
    • entry_kick_result_location_rotated_y_std: The y coordinate of the inside 50 result location transformed to a standard ground dimension (160x141) & rotated to give all squads attacking left-to-right.

match_transactions​

def match_transactions(match_id: int, **kwargs) -> pandas.DataFrame

Get the list of transactions for a match. Returns observed & not yet observed metrics.

Arguments:

  • match_id int - A unique numerical identifier of a match.
  • **kwargs - Arguments to be passed to internal functions, such as envir or version.

Raises:

  • Exception - Error when fetching data.

Returns:

  • pandas.DataFrame - A data frame with a list of transactions for a match.
    • match_id : A unique numerical identifier for a match.
    • trx_id : A unique numerical identifier for a given transaction, used for ordering chronologically.
    • stat_code : The statistic code for a given transaction.
    • stat_desc : A short description of the statistic code for a transaction.
    • period : The period of the transaction.
    • period_secs : The elapsed time within the period of a transaction.
    • score_home : The score of the home squad.
    • score_away : The score of the away squad.
    • squad_name : The name of the squad.
    • squad_code : A short code to represent the squad.
    • squad_id : A unique numerical identifier for the squad.
    • person_full_name : The fullname of the player assigned to the transaction (if applicable).
    • person_display_name : The display name of the player assigned to the transaction (if applicable).
    • person_id : A unique numerical identifier for the player assigned to the transaction (if applicable).
    • pressure_squad_name : The name of the squad the pressure information is assigned to.
    • pressure_squad_id : A unique numerical identifier for the squad the pressure information is assigned to.
    • pressure_squad_code : A short code to represent the squad the pressure information is assigned to.
    • pressure_name : The name of the type of pressure applied (ie. Set Position).
    • pressure_code : A short code to represent the type of pressure applied.
    • pressure_points : The points value of the type of pressure applied.
    • pressure_fullname1 : The fullname of the first pressure player.
    • pressure_displayname1 : The display name of the first pressure player.
    • pressure_personid1 : A unique numerical identifier for the first pressure player.
    • pressure_role1 : The role number of the first pressure player (1).
    • pressure_fullname2 : The fullname of the second pressure player.
    • pressure_displayname2 : The display name of the second pressure player.
    • pressure_personid2 : A unique numerical identifier for the second pressure player.
    • pressure_role2 : The role number of the second pressure player (2).
    • zone_physical : The zone in which the transaction takes place, relative to the physical ground.
    • zone_logical : The zone in which the transaction takes place, relative to the squad in possession.
    • location_x : The x coordinate of the transaction.
    • location_y : The y coordinate of the transaction.
    • location_x_std : The x coordinate of the transaction transformed to a standard ground dimension (160x141).
    • location_y_std : The y coordinate of the transaction transformed to a standard ground dimension (160x141).
    • location_rotated_x : The x coordinate of the transaction rotated to give all squads attacking left-to-right.
    • location_roated_y : The y coordinate of the transaction rotated to give all squads attacking left-to-right.
    • location_rotated_x_std: The x coordinate of the transaction transformed to a standard ground dimension (160x141) & rotated to give all squads attacking left-to-right.
    • location_rotated_y_std: The y coordinate of the transaction transformed to a standard ground dimension (160x141) & rotated to give all squads attacking left-to-right.
    • kicking_foot : On kicking transactions, the foot of the kicking player.
    • kicking_intent : On kicking transactions, the intent of the kicking player.
    • kicking_distance : On kicking transactions, a description of the kicks distance.
    • kicking_direction : On kicking transactions, a description of the kicks direction.
    • inside50_direction : On inside 50 transactions, a description of the kicks direction.
    • inside50_intent : On inside 50 transactions, the intent of the kicking player.
    • shot_angle : A text description of the angle of the shot.
    • shot_distance : A text description of the distance of the shot.
    • shot_result : The result of the shot on goal (Does not include Goals).
    • shot_source : The source from which the shot on goal resulted (ie. General Play).
    • shot_type : The type of shot attempted (ie. General Play Snap).
    • free_kick_context : On free kick transactions, the broad context from which the free kick was awarded.
    • free_kick_reason : On free kick transactions, the specific reason the free kick was awarded.
    • kick_in_direction : On kick in transactions, a text description of the direction taken from the kick in.

Examples:

api.match_transactions(match_id=120390401)

bench​

def bench(match_id: int) -> pandas.DataFrame

Get the current bench status of all players in a match.

Arguments:

  • match_id int - A unique numerical identifier of a match.

Returns:

  • pandas.DataFrame - A data frame with a list of all players for the match and their current bench status.
    • display_name: The display name of the player, represented as first initial and surname.
    • full_name : The full name of the player.
    • person_id : A unique numerical identifier of the player.
    • elapsed : Seconds elapsed within the current period since the player's last interchange move.
    • status : The player's current status.
    • squad_code : A short code to represent the squad.
    • squad_id : A unique numerical identifier of the squad.
    • squad_name : The name of the squad.
    • match_id : A unique numerical identifier of a match.

Examples:

api.bench(match_id=120390401)

match​

def match(match_id: int) -> pandas.DataFrame

Get details about a match.

Arguments:

  • match_id int - An unique numerical identifier of a match.

Returns:

  • pandas.DataFrame - A data frame with details about a match.
    • competition_name : The full name of the competition.
    • season_id : A numerical identifier of a season.
    • type_id : A numerical indicator of the match type.
    • type_name : A description of the match type.
    • type_code : A short code describing the match type.
    • round_number : The round number of the match. Continues to count up during finals.
    • round_phase_number: The round number of the match within the phase. Starts again from one for finals.
    • match_id : A unique numerical identifier of a match.
    • match_name : The name of the match. Concatenates home and away squad names.
    • match_code : A short code for the name of the match. Concatenates home and away squad codes.
    • match_start : The start time of a match in UTC time.
    • match_date : The calendar date of a match in local time.
    • match_time : The local start time of a match.
    • home_squad_id : A unique numerical identifier of the home squad.
    • home_squad_name : The name of the home squad.
    • home_squad_code : A short code to represent the home squad.
    • away_squad_id : A unique numerical identifier of the away squad.
    • away_squad_name : The name of the away squad.
    • away_squad_code : A short code to represent the away squad.
    • venue_id : A unique numerical identifier of the match venue.
    • venue_name : A unique numerical identifier of the match venue.
    • venue_code : A short code to represent the match venue.
    • venue_time_zone : The timezone of the venue.
    • status_id : A numerical identifier of the match's current status.
    • status_name : The match's current status.
    • status_type_id : A numerical identifier of the match status type.
    • status_type_name : The match's current status type.
    • home_squad_goals : The number of goals kicked by the home squad.
    • home_squad_behinds: The number of behinds kicked by the home squad.
    • home_squad_points : The number of points scored by the home squad.
    • away_squad_goals : The number of goals kicked by the away squad.
    • away_squad_behinds: The number of behinds kicked by the away squad.
    • away_squad_points : The number of points scored by the away squad.
    • winner_id : The squad ID of the winning team.
    • result : A text description of the match result.
    • result_code : A short text description of the match result.

Examples:

api.match(match_id=120390401)

shots​

def shots(match_id: int, **kwargs) -> pandas.DataFrame

Get a list of shots at goal for a match. Also includes rushed behinds.

Arguments:

  • match_id int - A unique numerical identifier of a match.

Returns:

  • pandas.DataFrame - A data frame with a list of shots at goal for a match, with one row per shot.
    • match_id: A unique numerical identifier of a match.
    • match_trx_id: The transaction ID of the shot, used for ordering chronologically.
    • period: The period of the shot.
    • period_secs: The elapsed time within the period of the shot.
    • squad_id: A unique numerical identifier of the squad.
    • squad_name: The name of the squad.
    • squad_code: A short code to represent the squad.
    • person_id: A unique numerical identifier of the player taking the shot.
    • full_name: The full name of the player taking the shot.
    • display_name: The display name of the player taking the shot, represented as first initial and surname.
    • shot_origin: How the player was able to generate a shot at goal.
    • shot_type: The type of shot attempted.
    • shot_angle: A text description of the angle of the shot.
    • shot_distance: A text description of the distance of the shot.
    • location_x: Distance in metres from the centre of the ground (measuring goal to goal), with the goals being at positive (venue_length / 2).
    • location_y: Distance in metres from the centre of the ground (measuring boundary to boundary), with the goals being at zero and the boundary line at halfway being at (venue_widht / 2). Positive y is bottom of screen when running to the right.
    • standard_x: The x coordinate of the shot transformed to a standard ground dimension (160x141).
    • standard_y: The y coordinate of the shot transformed to a standard ground dimension (160x141).
    • expected_accuracy: The expected accuracy of the shot.
    • result: The result of the shot. G / B / R / M.
    • expected_points: The expected points of the shot.
    • points_result: The number of points obtained from the shot.

Examples:

api.shots(match_id=120390401)

metrics​

def metrics(match_id: int) -> pandas.DataFrame

Get a list of valid metrics for a match.

Arguments:

  • match_id int - An unique numerical identifier of a match.

Returns:

  • pandas.DataFrame - A data frame with a list of metrics for a match.
    • metric_id : A unique numerical identifier of a metric.
    • metric_code : The metric code (ALL_CAPS format).
    • metric_name : The metric name (singular).
    • metric_name_plural: The metric name (plural).
    • metric_name_short : An abbreviated metric name (max 25 characters).
    • metric_description: The text description of the metric definition.
    • level_id : A numerical identifier of the metric level.
    • level_name : The metric level (Squad, Player, or Both).
    • format_id : A numerical identifier of the metric format.
    • format_name : A numerical identifier of the metric format.
    • match_id : A unique numerical identifier of a match.

Examples:

api.metrics(match_id=120390401)

rotations​

def rotations(match_id: int) -> pandas.DataFrame

Get a list of rotations for a match.

Arguments:

  • match_id int - A unique numerical identifier of a match.

Returns:

  • pandas.DataFrame - A data frame with a list of rotations for the match, with one row per interchange move.
    • match_id : A unique numerical identifier of a match.
    • match_trx_id : The transaction ID of the interchange move, used for ordering chronologically.
    • period : The period of the interchange move.
    • period_secs : The elapsed time within the period of the interchange move.
    • squad_name : The name of the squad.
    • squad_code : A short code to represent the squad.
    • squad_id : A unique numerical identifier of the squad.
    • off_player_reason : The reason for the interchange move.
    • off_player_reason_code : A short text description of the reason for the interchange move.
    • off_player_full_name : The full name of the player coming off the ground.
    • off_player_display_name: The display name of the player coming off the ground, represented as first initial and surname.
    • off_person_id : A unique numerical identifier of the player coming off the ground.
    • on_player_full_name : The full name of the player coming on the ground. Empty for start-of-match initialisation of the interchange bench.
    • on_player_display_name : The display name of the player coming on the ground, represented as first initial and surname. Empty for start-of-match initialisation of the interchange bench.
    • on_person_id : A unique numerical identifier of the player coming on the ground. Empty for start-of-match initialisation of the interchange bench.

Examples:

api.rotations(match_id=120390401)

squad​

def squad(squad_id: int,
          season_id: int = None,
          league_id: int = 1,
          level_id: int = 1) -> pandas.DataFrame

Get details about a squad in a season.

Arguments:

  • squad_id int - A unique numerical identifier of a squad.
  • season_id int, optional - A numerical identifier of a season. If missing, defaults to the current season of the League Level defined by 'leagueId' and 'levelId'.
  • league_id int, optional - A unique numerical identifier of a league. Defaults to 1 (AFL Men's Premiership).
  • level_id int, optional - A unique numerical identifier of a level. Defaults to 1 (Seniors).

Returns:

  • pandas.DataFrame - A data frame with details about a squads.
    • season_id : A numerical identifier of a season.
    • squad_code: A short code to represent the squad.
    • squad_id : A unique numerical identifier of the squad.
    • squad_name: The name of the squad.
    • state_id : A numerical identifier of a country's state.
    • state_name: The squad's home state.
    • state_code: A short code representing the squad's home state.

Examples:

api.squad(squad_id=10, season_id=2022)
api.squad(squad_id=20)

score​

def score(match_id: int, cumulative: bool = False) -> pandas.DataFrame

Get a a list of match scores by quarter.

Arguments:

  • match_id int - A unique numerical identifier of a match.
  • cumulative bool, optional - Logical. Return scores up to and including that quarter? Defaults to FALSE, which returns scores within the quarter only. Defaults to False.

Returns:

  • pandas.DataFrame - A data frame with a list of quarters and scores for each quarter.
    • match_id : A unique numerical identifier of a match.
    • home_squad_id : A unique numerical identifier of the home squad.
    • home_squad_name : The name of the home squad.
    • home_squad_code : A short code to represent the home squad.
    • away_squad_id : A unique numerical identifier of the away squad.
    • away_squad_name : The name of the away squad.
    • away_squad_code : A short code to represent the away squad.
    • period : The period of the match.
    • home_squad_goals : Goals scored by the home squad.
    • home_squad_behinds : Behinds scored by the home squad.
    • home_squad_points : Points scored by the home squad.
    • home_squad_result : Period result for the home squad. W/L/D.
    • home_squad_margin : Scoreboard margin for the home squad.
    • away_squad_goals : Goals scored by the away squad.
    • away_squad_behinds : Behinds scored by the away squad.
    • away_squad_points : Points scored by the away squad.
    • away_squad_result : Period result for the away squad. W/L/D.
    • away_squad_margin : Scoreboard margin for the away squad.
    • winning_squad_id_match : The ID of the winning squad.
    • winning_squad_id_period: The ID of the winning squad.
    • cumulative : TRUE/FALSE based on the cumulative parameter passed to the function.

Examples:

api.score(match_id=120390401)
api.score(match_id=120390401, cumulative=True)

match_persons​

def match_persons(match_id: int) -> pandas.DataFrame

Get a list of persons involved in a match. Currently limited to the players or field umpires.

Arguments:

  • match_id int - An unique numerical identifier of a match.

Returns:

  • pandas.DataFrame - A data frame with a list of persons for a match, with one row per person.
    • match_id : A unique numerical identifier of the match.
    • squad_id : A unique numerical identifier of the squad. (Players only).
    • squad_name : The name of the squad. (Players only).
    • squad_code : A short code to represent the squad. (Players only).
    • person_id : A unique numerical identifier of a person.
    • full_name : The person's full name.
    • first_name : The person's first name.
    • surname : The person's surname.
    • display_name : The person's display name, represented as first initial and surname.
    • jumper_number : The number worn on the person's uniform.
    • selected_position_id : A numerical identifier of the person's selected position.
    • selected_position_name: The person's selected position.
    • selected_position_code: A short code representing the peron's selected position.
    • season_position_id : A numerical identifier of the person's primary position in that season. (Players only)
    • season_position_name : The person's primary position in that season. (Players only)
    • season_position_code : A short code representing the peron's primary position in that season. (Players only)
    • height : The person's height in centimetres. (Players only)
    • weight : The person's weight in kilograms. (Players only)
    • date_of_birth : The person's date of birth (YYYY-MM-DD). (Players only)
    • match_age : The person's age at the start of the match, to one decimal place. (Players only)

Examples:

api.match_persons(match_id=120390401)

leagues​

def leagues() -> pandas.DataFrame

Get information for all leagues in the API

Returns:

  • pandas.DataFrame - A data frame with details about leagues and levels.
    • league_id : A unique numerical identifier of the league.
    • league_name : The name of the league.
    • league_code : A short code representing the name of the league.
    • league_gender: A short code representing The gender of a league. "M" for Men's, "W" for Women's.

Examples:

api.leagues()

league​

def league(league_id: int = 1) -> pandas.DataFrame

Get details about a league.

Arguments:

  • league_id int, optional - A unique numerical identifier of a league. Defaults to 1 (AFL Men's Premiership).

Returns:

  • pandas.DataFrame - A data frame with details about a league and level.
    • league_id : A unique numerical identifier of the league.
    • league_name : The name of the league.
    • league_code : A short code representing the name of the league.
    • league_gender: A short code representing The gender of a league. "M" for Men's, "W" for Women's.

Examples:

api.league()

player_stats​

def player_stats(match_id: int,
                 period: Union[int, list[int]] = None,
                 zone: Literal["D50", "DM", "AM", "F50"] = None,
                 metric: Literal["TACKLE", "GOAL", "HANDBALL"] = None,
                 team: Literal["home", "away"] = None,
                 lastXseconds: int = None,
                 **kwargs) -> pandas.DataFrame

Get player stats for a match. Only returns observed metrics.

Arguments:

  • match_id int - A unique numerical identifier of a match.
  • period Union[int, list[int]], optional - A numerical indicator of a period to filter results within a match. Accepts integer values. Defaults to None.
  • zone Literal["D50", "DM", "AM", "F50"], optional - A text indicator of a zone on the field to filter results within a match. Accepts string values "D50","DM","AM","F50". Defaults to None.
  • metric Literal["TACKLE", "GOAL", "HANDBALL"], optional - A text string of specific metric code(s) to be returned. This will result in the endpoint only returning these specific metrics. Note this endpoint is case sensitive and only works with metric codes (ie. "TACKLE", "GOAL"). Defaults to None.
  • team Literal["home", "away"], optional - A (case-sensitive) text string of the team to return metrics for. Either "home" or "away". Not passing anything to this param will return both teams. Defaults to None.
  • lastXseconds int, optional - An integer that limits statistics to counting events that occurred in the last X number of seconds. (ie. lastXSeconds = 300 will return the last 5 minutes). Defaults to None.
  • **kwargs - Arguments to be passed to internal functions, such as envir or version.

Returns:

  • pandas.DataFrame - A data frame with a list of metrics for a match for each player.
    • match_id : A unique numerical identifier of a match.
    • squad_id : A unique numerical identifier of the squad.
    • squad_name : The name of the squad.
    • squad_code : A short code to represent the squad.
    • person_id : A unique numerical identifier of the player.
    • player_name : The full name of the player.
    • display_name : The display name of the player, represented as first initial and surname.
    • metric_code : The metric code (ALL_CAPS format).
    • metric_name : The metric name (singular).
    • metric_id : The unique numerical identifier for the given metric
    • metric_name_plural : The metric name (plural).
    • metric_value : The numeric metric value with no formatting applied.
    • metric_display_value: The formatted metric value as a text string.

Examples:

api.player_stats(match_id=249791223)
api.player_stats(
    match_id=249791223,
    zone=["F50"],
    metric=["TACKLE", "TACKLE"],
    team=["away"],
    lastXseconds=300,
)

leaders​

def leaders(match_id: int) -> pandas.DataFrame

Get leading five players for selected stats for a match.

Arguments:

  • match_id int - A unique numerical identifier of a match.

Returns:

  • pandas.DataFrame - A data frame with a list of the five leading players for selected metrics.
    • squad_id : A unique numerical identifier of the squad.
    • squad_name : The name of the squad.
    • squad_code : A short code to represent the squad.
    • order : Order within the metric with no ties. Ties in metric value are broken by ordering by player surname then firstname.
    • rank : Dense rank within metric, with ties presented as ties.method='min'.
    • value : The numeric metric value with no formatting applied.
    • display : The formatted metric value as a text string.
    • display_name : The display name of the player, represented as first initial and surname.
    • player_name : The full name of the player.
    • person_id : A unique numerical identifier of the player.
    • metric_code : The metric code (ALL_CAPS format).
    • metric_name : The metric name (singular).
    • metric_name_plural: The metric name (plural).
    • match_id : A unique numerical identifier of a match.

Examples:

api.leaders(match_id=120390401)

squad_stats​

def squad_stats(match_id: int,
                period: list[int] = None,
                zone: Literal["D50", "DM", "AM", "F50"] = None,
                context: Literal["For", "Against", "Diff"] = None,
                metric: Literal["TACKLE", "GOAL", "HANDBALL"] = None,
                team: Literal["home", "away"] = None,
                lastXseconds: int = None,
                **kwargs) -> pandas.DataFrame

Get squad stats for a match. Only returns observed metrics.

Arguments:

  • match_id int - A unique numerical identifier of a match.
  • period list[int], optional - A numerical indicator of a period to filter results within a match. Accepts integer values. Defaults to None.
  • zone Literal["D50", "DM", "AM", "F50"], optional - A text indicator of a zone on the field to filter results within a match. Accepts string values "D50","DM","AM","F50". Defaults to None.
  • context Literal["For", "Against", "Diff"], optional - A text indicator of the context for squad statistics. Accepts "For" "Against" or "Diff". Defaults to None.
  • metric Literal["TACKLE", "GOAL", "HANDBALL"], optional - A text string of specific metric code(s) to be returned. This will result in the endpoint only returning these specific metrics. Note this endpoint is case sensitive and only works with metric codes (ie. "TACKLE", "GOAL"). Defaults to None.
  • team Literal["home", "away"], optional - A (case-sensitive) text string of the team to return metrics for. Either "home" or "away". Not passing anything to this param will return both teams. Defaults to None.
  • lastXseconds int, optional - An integer that limits statistics to counting events that occurred in the last X number of seconds. (ie. lastXSeconds = 300 will return the last 5 minutes). Defaults to None.
  • **kwargs - Arguments to be passed to internal functions, such as envir or version.

Returns:

  • pandas.DataFrame - A data frame with a list of metrics for a match for each squad.
    • match_id : A unique numerical identifier of a match.
    • squad_id : A unique numerical identifier of the squad.
    • squad_name : The name of the squad.
    • squad_code : A short code to represent the squad.
    • metric_code : The metric code (ALL_CAPS format).
    • metric_name : The metric name (singular).
    • metric_id : The unique numerical identifier for the given metric.
    • metric_name_plural : The metric name (plural).
    • metric_value : The numeric metric value with no formatting applied.
    • metric_display_value: The formatted metric value as a text string.

Examples:

api.squad_stats(match_id=249791223)
api.squad_stats(
    match_id=249791223,
    zone=["F50"],
    context=["Against"],
    metric=["TACKLE", "TACKLE"],
    team=["away"],
    lastXseconds=300,
)

ladder​

def ladder(season_id: int = None,
           round_number: int = None,
           league_id: int = 1,
           level_id: int = 1,
           **kwargs) -> pandas.DataFrame

Get the ladder for a given season.

Arguments:

  • season_id int, optional - A numerical identifier of a season. If missing, defaults to the current season of the League Level defined by 'leagueId' and 'levelId'.
  • round_number int, optional - An integer indicating the round number you are interested in. Returns the ladder as it stood after that round had completed. Defaults to the current ladder, or end of Home & Away for past seasons.
  • league_id int, optional - A unique numerical identifier of a league. Defaults to 1 (AFL Men's Premiership).
  • level_id int, optional - A unique numerical identifier of a level. Defaults to 1 (Seniors).

Returns:

  • pandas.DataFrame - A data frame with the requested ladder, with one row per squad.
    • season_id : A numerical identifier of a season.
    • round_number : The round number of the match. Continues to count up during finals.
    • position : The squads ladder position.
    • squad_id : A unique numerical identifier of the squad.
    • squad_name : The name of the squad.
    • squad_code : A short code to represent the squad.
    • ladder_points : The number of ladder points accumulated by the squad.
    • ladder_percentage : The squad's ladder percentage, calculated by points scored divided by points conceded.
    • matches_played : The number of matches played by the squad.
    • played_wins : The number of matches the squad has won.
    • played_win_percentage: The percentage of completed matches the squad has won.
    • played_draws : The number of matches the squad has drawn.
    • played_losses : The number of matches the squad has lost.
    • total_score_for : The total number of points scored by the squad.
    • total_score_against : The total number of points conceded by the squad.
    • total_margin : The total points differential for the squad.
    • average_score_for : The average number of points scored by the squad per match.
    • average_score_against: The average number of points conceded by the squad per match.
    • average_margin : The average points differential for the squad per match.

Examples:

api.ladder(season_id=2022)
api.ladder(season_id=2022, round_number=4)
api.ladder()

chains​

def chains(match_id: int, **kwargs) -> pandas.DataFrame

Get a list of possession chains for a match.

Arguments:

  • match_id int - A unique numerical identifier of a match.

Returns:

  • pandas.DataFrame - A data frame with a list of possession chains for a match, with one row per chain. NULL if the match is yet to start.
    • match_id : A unique numerical identifier of a match.
    • squad_id : A unique numerical identifier of the squad.
    • squad_name : The name of the squad in possession during the chain.
    • squad_code : A short code to represent the squad in possession during the chain.
    • period : The period of the possession chain.
    • start_transaction_id : The transaction ID of the start of the chain.
    • start_period_secs : The elapsed time within the period at the start of the chain.
    • start_state_name : The starting state of the chain.
    • start_state_code : A short code representing the starting state of the chain.
    • start_state_type : The start type of the chain.
    • start_type_code : A short code representing the starting type of the chain.
    • start_zone : The starting zone of the chain, relative to the squad in possession.
    • start_zone_physical : The starting zone of the chain, relative to the physical ground.
    • start_x : The x-coordinate of the start of chain location.
    • start_y : The y-coordinate of the start of chain location.
    • launch_person_id : A unique numerical identifier of the player who launched the chain.
    • launch_player_name : The full name of the player who launched the chain.
    • launch_display_name : The display name of the player who launched the chain, represented as first initial and surname.
    • end_transaction_id : The transaction ID of the end of the chain.
    • end_period_secs : The elapsed time within the period at the end of the chain.
    • end_state_name : The final state of the chain.
    • end_state_code : A short code representing the final state of the chain.
    • end_state_type : The end type of the chain.
    • end_type_code : A short code representing the end type of the chain.
    • end_zone : The final zone of the chain, relative to the squad in possession.
    • end_zone_physical : The final zone of the chain, relative to the physical ground.
    • end_x : The x-coordinate of the end of chain location.
    • end_y : The y-coordinate of the end of chain location.
    • score_trx_id : The transaction ID of the scoring shot, if a score was generated during the chain.
    • score_result_code : The result scoring shot, if a score was generated during the chain.
    • score_result : A single letter representing the result scoring of the scoring shot, if a score was generated during the chain.
    • score_points : The points generated by the scoring shot, if a score was generated during the chain.
    • score_person_id : A unique numerical identifier of the player who scored within the chain.
    • score_player_name : The full name of the player who scored within the chain.
    • score_display_name : The display name of the player who scored within the chain, represented as first initial and surname.
    • turnover_person_id : A unique numerical identifier of the player who turned the ball over at the end of the chain.
    • turnover_player_name : The full name of the player who turned the ball overa at the end of the chain.
    • turnover_display_name : The display name of the player who turned the ball overa at the end of the chain, represented as first initial and surname.
    • turnover_type : The type of turnover that was commited. Kick, handball or non-disposal.
    • turnover_state : The match state of the turnover that was commited. Clearing stoppage or General Play.
    • turnover_creation : The creation method of the turnover that was commited. Forced/Unforced Giveaway or Opposition Takeaway.
    • clearance_trx_id : The transaction ID of the clearance that was won within the chain.
    • inside_50_trx_id : The transaction ID of the first inside 50 that was generated by the squad in possession within the chain.
    • rebound_50_trx_id : The transaction ID of the first rebound 50 that was generated by the squad in possession within the chain.
    • stoppage_trx_id : The first transaction ID of the chain in a stoppage chain.
    • next_chain_id : The transaction ID of the start of the next possession chain.
    • prev_chain_id : The transaction ID of the start of the previous possession chain.
    • chain_metres_gained : Metres gained by a team within possession chains, combining measures towards attacking goal and away from defensive goal.
    • chain_metres_gained_reply: Chain Metres conceded to the opposition in the next chain after a turnover.
    • chain_metres_gained_net : Net Metres gained in a chain of possession after subtracting opposition Metres gained after a turnover. Equal to Chain Metres minus Chain Metres Reply.

Examples:

api.chains(match_id=120390401)

season​

def season(season_id: int = None,
           league_id: int = 1,
           level_id: int = 1,
           **kwargs) -> pandas.DataFrame

Get details about a given season.

Arguments:

  • season_id int, optional - A numerical identifier of a season. If missing, defaults to the current season of the League Level defined by 'leagueId' and 'levelId'.
  • league_id int, optional - A unique numerical identifier of a league. Defaults to 1 (AFL Men's Premiership).
  • level_id int, optional - A unique numerical identifier of a level. Defaults to 1 (Seniors).

Returns:

  • pandas.DataFrame - A data frame with details about the given season.
    • season_id : A numerical identifier of a season.
    • competition_id : A unique numerical identifier of a competition, combining League, Level and Season.
    • competition_code : A short code describing the competition.
    • competition_name : The full name of the competition.
    • start_date : The date of the first match of the season 'YYYY-MM-DD'
    • start_year : The year of the first match of the season.
    • first_match_start : The datetime of the first match of the season.
    • end_date : The date of the final scheduled game of the season 'YYYY-MM-DD'.
    • end_year : The year of the final scheduled game of the season.
    • matches_complete : A count of the complete matches in the season.
    • matches_incomplete : A count of incomplete matches remaining in the season.
    • next_scheduled_round_number : The round number of the next round to start.
    • next_scheduled_round_start : The datetime of the first match of the next round to start, in UTC time.
    • last_round_completed_round_number: The round number of the last round to finish.
    • last_round_completed_end : The datetime of the end of the last match of the last round to finish, in UTC time.

Examples:

api.season(season_id=2022)
api.season()

level​

def level(league_id: int = 1, level_id: int = 1) -> pandas.DataFrame

Get details about a league and level.

Arguments:

  • league_id int, optional - A unique numerical identifier of a league. Defaults to 1 (AFL Men's Premiership).
  • level_id int, optional - A unique numerical identifier of a level. Defaults to 1 (Seniors).

Returns:

  • pandas.DataFrame - A data frame with details about a league and level.
    • level_id : A unique numerical identifier of the level.
    • level_name : The name of the level.
    • code : A short code representing the name of the level.
    • league_id : A unique numerical identifier of the league.
    • league_name : The name of the league.
    • league_code : A short code representing the name of the league.
    • gender : A short code representing The gender of a league. "M" for Men's, "W" for Women's.
    • current_season_id: The current season ID.

Examples:

api.level(league_id=1, level_id=1)
api.level()

levels​

def levels(league_id: int = 1) -> pandas.DataFrame

Get a list of available levels for a given league.

Arguments:

  • league_id int, optional - A unique numerical identifier of a league. Defaults to 1 (AFL Men's Premiership).

Returns:

  • pandas.DataFrame - A data frame with details about all levels of a given league.
    • level_id : A unique numerical identifier of the level.
    • level_name : The name of the level.
    • code : A short code representing the name of the level.
    • league_id : A unique numerical identifier of the league.
    • league_name: The name of the league.
    • league_code: A short code representing the name of the league.
    • gender : A short code representing The gender of a league. "M" for Men's, "W" for Women's.

Examples:

api.levels(league_id=1)
api.levels()

venue​

def venue(match_id: int) -> pandas.DataFrame

Get details about the venue for a match.

Arguments:

  • match_id int - An unique numerical identifier of a match.

Returns:

  • pandas.DataFrame - A data frame with details about the match venue.
    • venue_code : A short code to represent the match venue.
    • venue_id : A unique numerical identifier of the match venue.
    • match_id : A unique numerical identifier of a match.
    • venue_name : The name of the match venue.
    • length : The length of the venue in metres.
    • width : The width of the venue in metres.
    • country_code: A short code representing the country of the venue.
    • country_id : A unique numerical identifier of the country of the venue.
    • country_name: The country of the venue.
    • state_id : A numerical identifier of a country's state.
    • state_name : The venue's state.
    • state_code : A short code representing the venue's state.
    • timezone : The timezone of the venue.

Examples:

api.venue(match_id=120390401)

match_periods​

def match_periods(match_id: int, **kwargs) -> pandas.DataFrame

Get details about the periods of a match.

Arguments:

  • match_id int - A unique numerical identifier of a match.

Returns:

  • pandas.DataFrame - A data frame with details about each match period. Only contains periods that have started.
    • match_id : A unique numerical identifier of a match.
    • period : The period of the match.
    • period_secs : The elapsed time in seconds for live periods, or the period length for completed periods.
    • utc_period_start: The start time of the period in UTC time.
    • utc_period_end : The end time of the period in UTC time.

Examples:

api.match_periods(match_id=120390401)

squads​

def squads(season_id: int = None,
           league_id: int = 1,
           level_id: int = 1,
           **kwargs) -> pandas.DataFrame

Get a list of squads participating in a season.

Arguments:

  • season_id int, optional - A numerical identifier of a season. If missing, defaults to the current season of the League Level defined by 'leagueId' and 'levelId'.
  • league_id int, optional - A unique numerical identifier of a league. Defaults to 1 (AFL Men's Premiership).
  • level_id int, optional - A unique numerical identifier of a level. Defaults to 1 (Seniors).

Returns:

  • pandas.DataFrame - A data frame with a list of squads, with one row per squad.
    • season_id : A numerical identifier of a season.
    • squad_id : A unique numerical identifier of the squad.
    • squad_name: The name of the squad.
    • squad_code: A short code to represent the squad.

Examples:

api.squads(season_id=2022)
api.squads()

squad_persons​

def squad_persons(squad_id: int,
                  season_id: int = None,
                  league_id: int = 1,
                  level_id: int = 1,
                  **kwargs) -> pandas.DataFrame

Get a list of persons involved in a squad in a season. Currently limited to the playing list.

Arguments:

  • squad_id int - An identifier of the squad. Accepts a numerical squad ID.
  • season_id int, optional - A numerical identifier of a season. If missing, defaults to the current season of the League Level defined by 'leagueId' and 'levelId'.
  • league_id int, optional - A unique numerical identifier of a league. Defaults to 1 (AFL Men's Premiership).
  • level_id int, optional - A unique numerical identifier of a level. Defaults to 1 (Seniors).

Returns:

  • pandas.DataFrame - A data frame with a list of persons for a squad, with one row per person.
    • season_id : A numerical identifier of a season.
    • squad_name : The name of the squad.
    • squad_id : A unique numerical identifier of the squad.
    • person_id : A unique numerical identifier of a person.
    • first_name : The person's first name.
    • surname : The person's surname.
    • full_name : The person's full name.
    • display_name : The person's display name, represented as first initial and surname.
    • position : The person's primary position within a season. The position where a player has spent most time.
    • date_of_birth: The person's date of birth (YYYY-MM-DD).
    • season_age : The person's age in years at the start of the first game of the season, to one decimal place.
    • year_age : The person's age at December 31 of the year in which the season ends, rounded down to a whole year.
    • height : The person's height in centimetres.
    • weight : The person's weight in kilograms.

Examples:

api.squad_persons(squad_id=10, season_id=2022)

squad_lists​

def squad_lists(season_id: int = None,
                league_id: int = 1,
                level_id: int = 1,
                **kwargs) -> pandas.DataFrame

Get a list of persons involved in all squads in a season. Currently limited to the playing list.

Arguments:

  • season_id int, optional - A numerical identifier of a season. If missing, defaults to the current season of the League Level defined by 'leagueId' and 'levelId'.
  • league_id int, optional - A unique numerical identifier of a league. Defaults to 1 (AFL Men's Premiership).
  • level_id int, optional - A unique numerical identifier of a level. Defaults to 1 (Seniors).

Returns:

  • pandas.DataFrame - A data frame with a list of persons for all squads, with one row per person.
    • season_id : A numerical identifier of a season.
    • squad_name : The name of the squad.
    • squad_id : A unique numerical identifier of the squad.
    • person_id : A unique numerical identifier of a person.
    • first_name : The person's first name.
    • surname : The person's surname.
    • full_name : The person's full name.
    • display_name : The person's display name, represented as first initial and surname.
    • position : The person's primary position within a season. The position where a player has spent most time.
    • date_of_birth: The person's date of birth (YYYY-MM-DD).
    • season_age : The person's age in years at the start of the first game of the season, to one decimal place.
    • year_age : The person's age at December 31 of the year in which the season ends, rounded down to a whole year.
    • height : The person's height in centimetres.
    • weight : The person's weight in kilograms.

Examples:

api.squad_lists(season_id=2022)

fixture​

def fixture(season_id: int,
            league_id: int = 1,
            level_id: int = 1) -> pandas.DataFrame

Get the fixture for a given season.

Arguments:

  • season_id int - A numerical identifier of a season. If missing, defaults to the current season of the League Level defined by 'leagueId' and 'levelId'.
  • league_id int, optional - A unique numerical identifier of a league. Defaults to 1 (AFL Men's Premiership).
  • level_id int, optional - A unique numerical identifier of a level. Defaults to 1 (Seniors).

Returns:

  • pandas.DataFrame - A data frame with the fixture for a given season, with one row per match.
    • match_id : A unique numerical identifier of a match.
    • match_order : The order of a match within a round, sorted by start date and time.
    • away_squad_goals : The number of goals kicked by the away squad.
    • away_squad_behinds: The number of behinds kicked by the away squad.
    • away_squad_points : The number of points scored by the away squad.
    • away_squad_code : A short code to represent the away squad.
    • away_squad_id : A unique numerical identifier of the away squad.
    • away_squad_name : The name of the away squad.
    • home_squad_goals : The number of goals kicked by the home squad.
    • home_squad_behinds: The number of behinds kicked by the home squad.
    • home_squad_points : The number of points scored by the home squad.
    • home_squad_code : A short code to represent the home squad.
    • home_squad_id : A unique numerical identifier of the home squad.
    • home_squad_name : The name of the home squad.
    • match_date : The calendar date of a match in local time.
    • match_time : The local start time of a match.
    • match_start : The start time of a match in UTC time.
    • status_id : A numerical identifier of the match's current status.
    • status_name : The match's current status.
    • status_type_id : A numerical identifier of the match status type.
    • status_type_name : The match's current status type.
    • type_id : A numerical indicator of the match type.
    • type_name : A description of the match type.
    • venue_id : A unique numerical identifier of the match venue.
    • venue_code : A short code to represent the match venue.
    • venue_name : The name of the match venue.
    • competition_code : A short code describing the competition.
    • season_id : A numerical identifier of a season.
    • phase_code : A short code describing the phase of the season.
    • round_code : A short code representing the name of the round.
    • round_number : The round number of the match. Continues to count up during finals.
    • round_phase_number: The round number of the match within the phase. Starts again from one for finals.

Examples:

api.fixture(season_id=2022)
api.fixture() # ERROR: Currently not available. A season id must be provided.

to_minsec​

def to_minsec(x: int, leading_zero: bool = False) -> str

Convert an integer of seconds elapsed to a text string with minutes and seconds.

Arguments:

  • x int - Seconds, as an integer.
  • leading_zero bool, optional - Logical. Add a leading zero to minute values less than 10. Defaults to False.

Returns:

  • str - A text string in the form "MI:SS" - eg. "9:54" if @param leadingZero is FALSE, "09:54" if @param leadingZero is TRUE.
Last updated on