Skip to main content

AFL API R Package Documentation

Details​

Package: cdAFLAPI
Version: 1.4.7
Author: Champion Data
Maintainer: Aaron Brougham <aaron.brougham@championdata.com.au>

cdAPI: Champion Data AFL API​

Description​

Hit the Champion Data AFL API with a given endpoint.

Usage​

cdAPI(
  endpoint,
  envir = c("", "sandbox", "dev"),
  base_url = "https://api.afl.championdata.io",
  version = "v1",
  df = TRUE
)

Arguments​

  • endpoint: The full path of an endpoint including path and query parameters, excluding the base_url and version components. eg: "Leagues" rather than "https://api.afl.championdata.io/v1/Leagues"
  • envir: A short code representing the environment to hit. Empty string = Production, 'sandbox' = Sandbox environment, 'dev' = Development environment (Internal Champion Data use only).
  • base_url: The base URL for the API. Defaults to the AFL API.
  • version: The version number of the API. Defaults to 1.
  • df: Logical. Convert to data.frame? Note: Will only work for endpoints with a flat JSON response.

Value​

A numerical value for league ID.

Examples​

cdAPI('matches/113770401')

cdAPIPOSTresponse: Champion Data AFL API Response (POST Endpoint)​

Description​

Hit either the Players or Squads Champion Data AFL API via the POST Endpoint.

Usage​

cdAPIPOSTresponse(
  matchId,
  endpoint,
  payload,
  baseUrl = "https://api.afl.championdata.io",
  version = "v1",
  envir = ""
)

Arguments​

  • matchId: A unique numerical identifier of a match.
  • endpoint: A (case-insensitive) string detailing which endpoint to hit (either 'player' or 'squad').
  • payload: A nested list containing the parcels of data to be returned by the API. See: createPayload() as a method of simplifying this step.
  • version: The version number of the API. Defaults to 1.
  • envir: A short code representing the environment to hit. Empty string = Production, 'sandbox' = Sandbox environment, 'dev' = Development environment (Internal Champion Data use only).
  • base_url: The base URL for the API. Defaults to the AFL API.

Value​

A response object from the API call.

Examples​

cdAPIPOSTresponse(matchId = 120390401, endpoint = "player", payload = payload)

cdAPIresponse: Champion Data AFL API Response​

Description​

Hit the Champion Data AFL API with a given endpoint to retrieve a response object.

Usage​

cdAPIresponse(
  matchId,
  endpoint,
  envir = c("", "sandbox", "dev"),
  base_url = "https://api.afl.championdata.io",
  version = "v1"
)

Arguments​

  • matchId: A unique numerical identifier of a match (only required for match-level endpoints.)
  • endpoint: The full path of an endpoint including path and query parameters, excluding the base_url and version components. eg: "Leagues" rather than "https://api.afl.championdata.io/v1/Leagues"
  • envir: A short code representing the environment to hit. Empty string = Production, 'sandbox' = Sandbox environment, 'dev' = Development environment (Internal Champion Data use only).
  • base_url: The base URL for the API. Defaults to the AFL API.
  • version: The version number of the API. Defaults to 1.

Value​

A response object.

Examples​

cdAPIresponse(matchId,paste('matches',matchId,'entries',sep='/')

createPayLoad: createPayload​

Description​

Create a payload for getPlayerStatsPOST() and getSquadStatsPOST() functions.

Usage​

createPayLoad(endpoint, ...)

Arguments​

  • endpoint: A string of either "player" or "squad" dictating the POST endpoint the payload is being built for.
  • list(s): Pass in any number of single lists to be combined into one payload.

Value​

A nested list in the correct structure to pass into payload arguments of getPlayerStatsPOST() and getSquadStatsPOST()

Examples​

D50_Tackles_Q1 = list(metricCodes = list("TACKLE"), zones = list('D50'), periods = list(1), id = "D50_Tackles_Q1")
createPayLoad(endpoint = "squad", D50_Tackles_Q1)

getBench: Match Bench​

Description​

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

Usage​

getBench(matchId, ...)

Arguments​

  • matchId: A unique numerical identifier of a match.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

A data frame with a list of all players for the match and their current bench status.

  • 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.
  • id A unique numerical identifier of the player.
  • name The full name of the player.
  • display The display name of the player, represented as first initial and surname.
  • status The player's current status.
  • elapsed Seconds elapsed within the current period since the player's last interchange move.

Examples​

getBench(216085122)

getChains: Match Chains​

Description​

Get a list of possession chains for a match.

Usage​

getChains(matchId, ...)

Arguments​

  • matchId: A unique numerical identifier of a match.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.id The transaction ID of the start of the chain.
  • start.secs The elapsed time within the period at the start of the chain.
  • start.name The starting state of the chain.
  • start.code A short code representing the starting state of the chain.
  • start.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.
  • launch.id A unique numerical identifier of the player who launched the chain.
  • launch.name The full name of the player who launched the chain.
  • launch.display The display name of the player who launched the chain, represented as first initial and surname.
  • end.id The transaction ID of the end of the chain.
  • end.secs The elapsed time within the period at the end of the chain.
  • end.name The final state of the chain.
  • end.code A short code representing the final state of the chain.
  • end.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.id The transaction ID of the scoring shot, if a score was generated during the chain.
  • score.result The result 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.player.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.player.display The display name of the player who scored within the chain, represented as first initial and surname.
  • turnover.id A unique numerical identifier of the player who turned the ball over at the end of the chain.
  • turnover.name The full name of the player who turned the ball overa at the end of the chain.
  • turnover.display 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.id The transaction ID of the clearance that was won within the chain.
  • inside50.id The transaction ID of the first inside 50 that was generated by the squad in possession within the chain.
  • rebound50.id The transaction ID of the first rebound 50 that was generated by the squad in possession within the chain.
  • next.id The transaction ID of the start of the next possession chain.
  • prevoius.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​

getChains(216085122)

getCurrentSeason: Current Season​

Description​

Get current season for a league and level.

Usage​

getCurrentSeason(leagueId = 1, levelId = 1, ...)

Arguments​

  • leagueId: A unique numerical identifier of a league. Defaults to AFL Men's Premiership.
  • levelId: A unique numerical identifier of a level. Defaults to Seniors.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

A numerical value for season ID.

Examples​

getCurrentSeason(1,1)
getCurrentSeason()

getEntries: Match Entries​

Description​

Get a list of Inside 50 entries for a match.

Usage​

getEntries(matchId, ...)

Arguments​

  • matchId: A unique numerical identifier of a match.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.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.kick.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.

Examples​

getEntries(216085122)

getFixture: Fixture​

Description​

Get the fixture for a given season.

Usage​

getFixture(seasonId, leagueId = 1, levelId = 1, ...)

Arguments​

  • seasonId: A numerical identifier of a season. If missing, defaults to the current season of the League Level defined by 'leagueId' and 'levelId'.
  • leagueId: A unique numerical identifier of a league. Defaults to AFL Men's Premiership.
  • levelId: A unique numerical identifier of a level. Defaults to Seniors.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

A data frame with the fixture for a given season, with one row per match.

  • 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.
  • type.id A numerical indicator of the match type.
  • type.name A description of the match type.
  • round.number The round number of the match. Continues to count up during finals.
  • round.phaseNumber The round number of the match within the phase. Starts again from one for finals.
  • round.code A short code representing the name of the round.
  • 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.
  • 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.id A unique numerical identifier of the home squad.
  • home.name The name of the home squad.
  • home.code A short code to represent the home squad.
  • away.id A unique numerical identifier of the away squad.
  • away.name The name of the away squad.
  • away.code A short code to represent the away squad.
  • venue.id A unique numerical identifier of the match venue.
  • venue.name The name of the match venue.
  • venue.code A short code to represent the match 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.goals The number of goals kicked by the home squad.
  • home.behinds The number of behinds kicked by the home squad.
  • home.points The number of points scored by the home squad.
  • away.goals The number of goals kicked by the away squad.
  • away.behinds The number of behinds kicked by the away squad.
  • away.points The number of points scored by the away squad.

Examples​

getFixture(2022)
getFixture()

getLadder: Ladder​

Description​

Get the ladder for a given season.

Usage​

getLadder(seasonId, roundNumber, leagueId = 1, levelId = 1, ...)

Arguments​

  • seasonId: A numerical identifier of a season. If missing, defaults to the current season of the League Level defined by 'leagueId' and 'levelId'.
  • roundNumber: 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.
  • leagueId: A unique numerical identifier of a league. Defaults to AFL Men's Premiership.
  • levelId: A unique numerical identifier of a level. Defaults to Seniors.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.
  • played The number of matches played by the squad.
  • win The number of matches the squad has won.
  • win.pct The percentage of completed matches the squad has won.
  • draw The number of matches the squad has drawn.
  • loss The number of matches the squad has lost.
  • total.for The total number of points scored by the squad.
  • total.against The total number of points conceded by the squad.
  • total.margin The total points differential for the squad.
  • average.for The average number of points scored by the squad per match.
  • average.against The average number of points conceded by the squad per match.
  • average.margin The average points differential for the squad per match.

Examples​

getLadder(2022)
getLadder(2022,4)
getLadder()

getLeaders: Match Stat Leaders​

Description​

Get leading five players for selected stats for a match.

Usage​

getLeaders(matchId, ...)

Arguments​

  • matchId: A unique numerical identifier of a match.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

A data frame with a list of the five leading players for selected metrics.

  • match.id A unique numerical identifier of a match.
  • code The metric code (ALL_CAPS format).
  • name The metric name (singular).
  • plural The metric name (plural).
  • player.id A unique numerical identifier of the player.
  • player.name The full name of the player.
  • player.display The display name of the player, represented as first initial and surname.
  • 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.
  • value The numeric metric value with no formatting applied.
  • display The formatted metric value as a text string.
  • rank Dense rank within metric, with ties presented as ties.method='min'.
  • order Order within the metric with no ties. Ties in metric value are broken by ordering by player surname then firstname.

Examples​

getLeaders(216085122)

getLeague: League Details​

Description​

Get details about a league.

Usage​

getLeague(leagueId = 1, ...)

Arguments​

  • leagueId: A unique numerical identifier of a league. Defaults to AFL Men's Premiership.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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​

getLeague(1)
getLeague()

getLeagueId: League ID​

Description​

Get the ID of a known league.

Usage​

getLeagueId(leagueCode = "AFL", ...)

Arguments​

  • leagueCode: A short code for a league. Defaults to AFL Men's Premiership.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

A numerical value for league ID.

Examples​

getLeagueId('AFL')
getLeagueId()

getLeagueLevel: League Level Details​

Description​

Get details about a league and level.

Usage​

getLeagueLevel(leagueId = 1, levelId = 1, ...)

Arguments​

  • leagueId: A unique numerical identifier of a league. Defaults to AFL Men's Premiership.
  • levelId: A unique numerical identifier of a level. Defaults to Seniors.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.
  • level.id A unique numerical identifier of the level.
  • level.name The name of the level.
  • level.code A short code representing the name of the level.
  • currentSeason.id The current season ID.

Examples​

getLeagueLevel(1,1)
getLeagueLevel()

getLeagueLevelId: League Level ID​

Description​

Get the ID of a known level for a league.

Usage​

getLeagueLevelId(leagueCode = "AFL", levelCode = "SEN", ...)

Arguments​

  • leagueCode: A short code for a league. Defaults to AFL Men's Premiership.
  • levelCode: A short code for a level. Defaults to Seniors.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

A data frame with a league ID and level ID.

  • league.id A unique numerical identifier of the league.
  • level.id A unique numerical identifier of the level.

Examples​

getLeagueLevelId('AFL','SEN')
getLeagueLevelId()

getMatch: Match Details​

Description​

Get details about a match.

Usage​

getMatch(matchId, ...)

Arguments​

  • matchId: An unique numerical identifier of a match.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.phaseNumber 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.id A unique numerical identifier of the home squad.
  • home.name The name of the home squad.
  • home.code A short code to represent the home squad.
  • away.id A unique numerical identifier of the away squad.
  • away.name The name of the away squad.
  • away.code A short code to represent the away squad.
  • venue.id A unique numerical identifier of the match venue.
  • venue.name The name of the match venue.
  • venue.code A short code to represent the match venue.
  • venue.timezone 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.goals The number of goals kicked by the home squad.
  • home.behinds The number of behinds kicked by the home squad.
  • home.points The number of points scored by the home squad.
  • away.goals The number of goals kicked by the away squad.
  • away.behinds The number of behinds kicked by the away squad.
  • away.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​

getMatch(216085122)

getMatchPeriods: Match Periods​

Description​

Get details about the periods of a match.

Usage​

getMatchPeriods(matchId, ...)

Arguments​

  • matchId: A unique numerical identifier of a match.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.
  • secs The elapsed time in seconds for live periods, or the period length for completed periods.
  • utcPeriodStart The start time of the period in UTC time.
  • utcPeriodEnd The end time of the period in UTC time.

Examples​

getMatchPeriods(216085122)

getMatchPersons: Match Persons​

Description​

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

Usage​

getMatchPersons(matchId, officials = FALSE, ...)

Arguments​

  • matchId: An unique numerical identifier of a match.
  • officials: Logical. Return match officials? Defaults to FALSE = Return players.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.
  • person.name The person's full name.
  • person.firstname The person's first name.
  • person.surname The person's surname.
  • person.display The person's display name, represented as first initial and surname.
  • jumper The number worn on the person's uniform.
  • selected.id A numerical identifier of the person's selected position.
  • selected.name The person's selected position.
  • selected.code A short code representing the peron's selected position.
  • position.id A numerical identifier of the person's primary position in that season. (Players only)
  • position.name The person's primary position in that season. (Players only)
  • 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)
  • DOB The person's date of birth (YYYY-MM-DD). (Players only)
  • age The person's age at the start of the match, to one decimal place. (Players only)

Examples​

getMatchPersons(216085122)
getMatchPersons(216085122,officials=TRUE)

getMatchTransactions: Match Transactions​

Description​

Get the list of transactions for a match. Returns a dataframe with fixed column length, irrespective of any fields having recorded values for match or not.

Usage​

getMatchTransactions(matchId, ...)

Arguments​

  • matchId: A unique numerical identifier of a match.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.fullname The fullname of the player assigned to the transaction (if applicable).
  • person.displayName 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.rotated.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).
  • freekick.context On free kick transactions, the broad context from which the free kick was awarded.
  • freekick.reason On free kick transactions, the specific reason the free kick was awarded.
  • kickin.direction On kick in transactions, a text description of the direction taken from the kick in.

Examples​

getMatchTransactions(216085122)

getMetrics: Match Metrics​

Description​

Get a list of valid metrics for a match.

Usage​

getMetrics(matchId, ...)

Arguments​

  • matchId: An unique numerical identifier of a match.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

A data frame with a list of metrics for a match.

  • match.id A unique numerical identifier of a match.
  • id A unique numerical identifier of a metric.
  • name The metric name (singular).
  • plural The metric name (plural).
  • code The metric code (ALL_CAPS format).
  • short An abbreviated metric name (max 25 characters).
  • 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.id A numerical identifier of the metric format.
  • description The text description of the metric definition.

Examples​

getMetrics(216085122)

getPeriodScores: Period Scores​

Description​

Get a a list of match scores by quarter.

Usage​

getPeriodScores(matchId, cumulative = FALSE, ...)

Arguments​

  • matchId: A unique numerical identifier of a match.
  • cumulative: Logical. Return scores up to and including that quarter? Defaults to FALSE, which returns scores within the quarter only.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

A data frame with a list of quarters and scores for each quarter.

  • match.id A unique numerical identifier of a match.
  • id The transaction ID of the interchange move, used for ordering chronologically.
  • home.id A unique numerical identifier of the home squad.
  • home.name The name of the home squad.
  • home.code A short code to represent the home squad.
  • away.id A unique numerical identifier of the away squad.
  • away.name The name of the away squad.
  • away.code A short code to represent the away squad.
  • period The period of the match.
  • home.goals Goals scored by the home squad.
  • home.behinds Behinds scored by the home squad.
  • home.points Points scored by the home squad.
  • home.result Period result for the home squad. W/L/D.
  • home.margin Scoreboard margin for the home squad.
  • away.goals Goals scored by the away squad.
  • away.behinds Behinds scored by the away squad.
  • away.points Points scored by the away squad.
  • away.result Period result for the away squad. W/L/D.
  • away.margin Scoreboard margin for the away squad.
  • winning.squad.id The ID of the winning squad.

Examples​

getPeriodScores(216085122)
getPeriodScores(216085122,cumulative=TRUE)

getPlayerStats: Match Player Stats​

Description​

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

Usage​

getPlayerStats(matchId, period, zone, metric, team, lastXseconds, ...)

Arguments​

  • matchId: A unique numerical identifier of a match.
  • period: A numerical indicator of a period to filter results within a match. Accepts integer values.
  • zone: A text indicator of a zone on the field to filter results within a match. Accepts string values "D50","DM","AM","F50".
  • metric: 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. c("TACKLE", "GOAL")
  • team: 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.
  • lastXseconds: 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)
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.
  • player.id A unique numerical identifier of the player.
  • player.name The full name of the player.
  • player.display The display name of the player, represented as first initial and surname.
  • code The metric code (ALL_CAPS format).
  • name The metric name (singular).
  • plural The metric name (plural).
  • value The numeric metric value with no formatting applied.
  • display The formatted metric value as a text string.

Examples​

getPlayerStats(216085122)
getPlayerStats(216085122,period=1,zone='D50')

getPlayerStatsPOST: Match Player Stats (POST Endpoint)​

Description​

Get player stats for a match via a payload to the POST endpoint.

Usage​

getPlayerStatsPOST(matchId, payload, info = FALSE, verbose = FALSE, ...)

Arguments​

  • matchId: A unique numerical identifier of a match.
  • payload: A nested list containing the parcels of data to be returned by the API. See: createPayload() as a method of simplifying this step.
  • info: A logical (TRUE/FALSE) to include the payload information alongside the data for each payload. Defaults to FALSE
  • verbose: A logical (TRUE/FALSE) indicating whether to enable verbose messaging to the console. When set to TRUE, the function will print additional information and progress messages to the console to provide a more detailed view of its execution. Defaults to FALSE for a quieter output.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

A data frame with a list of metrics supplied by the payload for each player in a match.

  • match.id A unique numerical identifier of a match.
  • 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.
  • player.name The full name of the player.
  • player.display The display name of the player, represented as first initial and surname.
  • player.id A unique numerical identifier of the player.
  • stat.code The metric code (ALL_CAPS format).
  • stat.name The metric name (singular).
  • stat.plural The metric name (plural).
  • value The numeric metric value with no formatting applied.
  • display The formatted metric value as a text string.
  • id A unique identifier string able to be supplied by the user for each list in the payload. Defaults to numerical index starting at 0.
  • info.metric.codes (when info = TRUE) The metric code(s) supplied to the specific list in the payload for that row of data.
  • info.periods (when info = TRUE) The period(s) supplied to the specific list in the payload for that row of data.
  • info.zones (when info = TRUE) The zone(s) supplied to the specific list in the payload for that row of data.
  • info.team (when info = TRUE) The team supplied to the specific list in the payload for that row of data.
  • info.context (when info = TRUE) The match context supplied to the specific list in the payload for that row of data.

Examples​

getSquadStatsPOST(matchId = 120390401, payload = squadPayload, info = T, verbose = T)

getRotations: Match Rotations​

Description​

Get a list of rotations for a match.

Usage​

getRotations(matchId, ...)

Arguments​

  • matchId: A unique numerical identifier of a match.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.
  • id The transaction ID of the interchange move, used for ordering chronologically.
  • 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.
  • period The period of the interchange move.
  • secs The elapsed time within the period of the interchange move.
  • off.id A unique numerical identifier of the player coming off the ground.
  • off.name The full name of the player coming off the ground.
  • off.display The display name of the player coming off the ground, represented as first initial and surname.
  • off.reason The reason for the interchange move.
  • off.code A short text description of the reason for the interchange move.
  • on.id A unique numerical identifier of the player coming on the ground. Empty for start-of-match initialisation of the interchange bench.
  • on.name The full name of the player coming on the ground. Empty for start-of-match initialisation of the interchange bench.
  • on.display 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.

Examples​

getRotations(216085122)

getSeason: Season Details​

Description​

Get details about a given season.

Usage​

getSeason(seasonId, leagueId = 1, levelId = 1, ...)

Arguments​

  • seasonId: A numerical identifier of a season. If missing, defaults to the current season of the League Level defined by 'leagueId' and 'levelId'.
  • leagueId: A unique numerical identifier of a league. Defaults to AFL Men's Premiership.
  • levelId: A unique numerical identifier of a level. Defaults to Seniors.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.
  • startDate The date of the first match of the season 'YYYY-MM-DD'.
  • startYear The year of the first match of the season.
  • endDate The date of the final scheduled game of the season 'YYYY-MM-DD'.
  • endYear The year of the final scheduled game of the season.
  • complete A count of the complete matches in the season.
  • incomplete A count of incomplete matches remaining in the season.
  • nextRound The round number of the next round to start.
  • nextRoundStart The datetime of the first match of the next round to start, in UTC time.
  • lastRound The round number of the last round to finish.
  • lastRoundEnd The datetime of the end of the last match of the last round to finish, in UTC time.
  • firstMatchStart The datetime of the first match of the season.

Examples​

getSeason(2022)
getSeason()

getShots: Match Shots​

Description​

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

Usage​

getShots(matchId, ...)

Arguments​

  • matchId: A unique numerical identifier of a match.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.
  • id The transaction ID of the shot, used for ordering chronologically.
  • period The period of the shot.
  • 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.
  • player.id A unique numerical identifier of the player taking the shot.
  • player.name The full name of the player taking the shot.
  • player.display The display name of the player taking the shot, represented as first initial and surname.
  • origin How the player was able to generate a shot at goal.
  • type The type of shot attempted.
  • angle A text description of the angle of the shot.
  • distance A text description of the distance of the shot.
  • x Distance of the shot in metres from the centre of the ground (measuring horizontally from goal to goal), with the goals being at positive (venue_length / 2).
  • y Distance of the shot in metres from the centre of the ground (measuring vertically from wing to wing), with the goals being at zero and the boundary line at halfway being at (venue_width / 2). Positive y is bottom of screen when running to the right.
  • x.std The x coordinate of the shot transformed to a standard ground dimension (160x141).
  • y.std The y coordinate of the shot transformed to a standard ground dimension (160x141).
  • accuracy.exp The expected accuracy of the shot.
  • result The result of the shot. G / B / R / M.
  • points.exp The expected points of the shot.
  • points The number of points obtained from the shot.

Examples​

getShots(216085122)

getSquad: Squad Details​

Description​

Get details about a squad in a season.

Usage​

getSquad(squadId, seasonId, leagueId = 1, levelId = 1, ...)

Arguments​

  • squadId: A unique numerical identifier of a squad.
  • seasonId: A numerical identifier of a season. If missing, defaults to the current season of the League Level defined by 'leagueId' and 'levelId'.
  • leagueId: A unique numerical identifier of a league. Defaults to AFL Men's Premiership.
  • levelId: A unique numerical identifier of a level. Defaults to Seniors.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

A data frame with details about a squads.

  • season.id A numerical identifier of a season.
  • id A unique numerical identifier of the squad.
  • name The name of the squad.
  • code A short code to represent 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​

getSquad(10,2022)
getSquad(20)

getSquadLists: Squad Person Lists​

Description​

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

Usage​

getSquadLists(seasonId, leagueId = 1, levelId = 1, ...)

Arguments​

  • seasonId: A numerical identifier of a season. If missing, defaults to the current season of the League Level defined by 'leagueId' and 'levelId'.
  • leagueId: A unique numerical identifier of a league. Defaults to AFL Men's Premiership.
  • levelId: A unique numerical identifier of a level. Defaults to Seniors.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.id A unique numerical identifier of the squad.
  • squad.name The name of the squad.
  • id A unique numerical identifier of a person.
  • firstname The person's first name.
  • surname The person's surname.
  • name The person's full name.
  • display 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.
  • DOB The person's date of birth (YYYY-MM-DD).
  • age.season The person's age in years at the start of the first game of the season, to one decimal place.
  • age.year 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​

getSquadLists(2022)

getSquadPersons: Squad Person List​

Description​

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

Usage​

getSquadPersons(squad, seasonId, leagueId = 1, levelId = 1, ...)

Arguments​

  • squad: An identifier of the squad. Accepts a numerical squad ID or a text squad name.
  • seasonId: A numerical identifier of a season. If missing, defaults to the current season of the League Level defined by 'leagueId' and 'levelId'.
  • leagueId: A unique numerical identifier of a league. Defaults to AFL Men's Premiership.
  • levelId: A unique numerical identifier of a level. Defaults to Seniors.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.id A unique numerical identifier of the squad.
  • squad.name The name of the squad.
  • id A unique numerical identifier of a person.
  • firstname The person's first name.
  • surname The person's surname.
  • name The person's full name.
  • display 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.
  • DOB The person's date of birth (YYYY-MM-DD).
  • age.season The person's age in years at the start of the first game of the season, to one decimal place.
  • age.year 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​

getSquadPersons(10,2022)
getSquadPersons('Carlton')

getSquads: Squad List​

Description​

Get a list of squads participating in a season.

Usage​

getSquads(seasonId, leagueId = 1, levelId = 1, ...)

Arguments​

  • seasonId: A numerical identifier of a season. If missing, defaults to the current season of the League Level defined by 'leagueId' and 'levelId'.
  • leagueId: A unique numerical identifier of a league. Defaults to AFL Men's Premiership.
  • levelId: A unique numerical identifier of a level. Defaults to Seniors.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

A data frame with a list of squads, with one row per squad.

  • season.id A numerical identifier of a season.
  • id A unique numerical identifier of the squad.
  • name The name of the squad.
  • code A short code to represent the squad.

Examples​

getSquads(2022)
getSquads()

getSquadStats: Match Squad Stats​

Description​

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

Usage​

getSquadStats(matchId, period, zone, context, metric, team, lastXseconds, ...)

Arguments​

  • matchId: A unique numerical identifier of a match.
  • period: A numerical indicator of a period to filter results within a match. Accepts integer values.
  • zone: A text indicator of a zone on the field to filter results within a match. Accepts string values "D50","DM","AM","F50".
  • context: A text indicator of the context for squad statistics. Accepts "For" "Against" or "Diff".
  • metric: 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. c("TACKLE", "GOAL")
  • team: 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.
  • lastXseconds: 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)
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

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.
  • code The metric code (ALL_CAPS format).
  • name The metric name (singular).
  • plural The metric name (plural).
  • value The numeric metric value with no formatting applied.
  • display The formatted metric value as a text string.

Examples​

getSquadStats(216085122)
getSquadStats(216085122,period=1,zone='D50')

getSquadStatsPOST: Match Squad Stats (POST Endpoint)​

Description​

Get squad stats for a match via a payload to the POST endpoint.

Usage​

getSquadStatsPOST(matchId, payload, info = FALSE, verbose = F, ...)

Arguments​

  • matchId: A unique numerical identifier of a match.
  • payload: A nested list containing the parcels of data to be returned by the API. See: createPayload() as a method of simplifying this step.
  • info: A logical (TRUE/FALSE) to include the payload information alongside the data for each payload. Defaults to FALSE
  • verbose: A logical (TRUE/FALSE) indicating whether to enable verbose messaging to the console. When set to TRUE, the function will print additional information and progress messages to the console to provide a more detailed view of its execution. Defaults to FALSE for a quieter output.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

A data frame with a list of metrics supplied by the payload for each player in a match.

  • match.id A unique numerical identifier of a match.
  • 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.
  • stat.code The metric code (ALL_CAPS format).
  • stat.name The metric name (singular).
  • stat.plural The metric name (plural).
  • value The numeric metric value with no formatting applied.
  • display The formatted metric value as a text string.
  • id A unique identifier string able to be supplied by the user for each list in the payload. Defaults to numerical index starting at 0.
  • info.metric.codes (when info = TRUE) The metric code(s) supplied to the specific list in the payload for that row of data.
  • info.periods (when info = TRUE) The period(s) supplied to the specific list in the payload for that row of data.
  • info.zones (when info = TRUE) The zone(s) supplied to the specific list in the payload for that row of data.
  • info.team (when info = TRUE) The team supplied to the specific list in the payload for that row of data.
  • info.context (when info = TRUE) The match context supplied to the specific list in the payload for that row of data.

Examples​

getSquadStatsPOST(matchId = 120390401, payload = squadPayload, info = T, verbose = T)

getVenue: Match Venue​

Description​

Get details about the venue for a match.

Usage​

getVenue(matchId, ...)

Arguments​

  • matchId: An unique numerical identifier of a match.
  • ...: Arguments to be passed to internal functions, such as envir or version.

Value​

A data frame with details about the match venue.

  • match.id A unique numerical identifier of a match.
  • id A unique numerical identifier of the match venue.
  • name The name of the match venue.
  • code A short code to represent the match venue.
  • country.id A unique numerical identifier of the country of the venue.
  • country.name The country of the venue.
  • country.code A short code representing 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.
  • length The length of the venue in metres.
  • width The width of the venue in metres.

Examples​

getVenue(216085122)

to_minsec: to_minsec​

Description​

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

Usage​

to_minsec(x, leadingZero = FALSE)

Arguments​

  • x: Seconds, as an integer.
  • leadingZero: Logical. Add a leading zero to minute values less than 10?

Value​

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

Examples​

to_minsec(594)
Last updated on