R Package Match Stats POST Functions

Overview

The Champion Data AFL API R Package allows users to connect to the Champion Data API and access the data contained in its endpoints. The functions listed below are designed to help users interact with the Player & Squads POST Endpoint(s) specifically. Further information about these functions is available in the package documentation.

Please ensure your authorised API credentials must be set in your R global environment as text strings under the variable names api_un (username) and api_pw (password).

Functions

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

getPlayerStatsPOST(matchId, payload, info=F, verbose=F)

These functions are for hitting the squads/players post endpoint and getting back a flattened dataframe in R, doing all the cleaning required to take the response from the endpoint and turn it into a dataframe. As inputs, these functions take a matchId & payload, and there are two optional parameters; info & verbose:

- info including the information from what you’ve called in the payload for context in the resulting dataframe.

- verbose providing verbose messaging to the console for more clarity on the function(s) execution. Both are set to FALSE by default.

Why use these functions?

The benefit of the POST functions are that, alongside being significantly faster, they allow you to make multiple different stat queries with one API call, where retrieving the same data via the regular stats functions would take longer and make more API calls.

If you're aiming to drive a match-day report or dashboard from the AFL API's match statistics, using these POST functions will deliver a better, more responsive report than using the regular functions, while also reducing your API calls and keep you within the daily call limit.

Payloads

The ‘payload’ refers to the packets of data being sent to the POST endpoint in a request, for the getSquadStatsPOST() & getPlayerStatsPOST() R functions defined above, a payload must be supplied as input to the functions. Payloads need to conform to a certain structure in order for the request to be processed by the server, for the getSquadStatsPOST() & getPlayerStatsPOST() functions, the payloads passed in as input need to be in a nested list structure which may be cumbersome to construct from scratch. As a result, we have created a helper function createPayload() to help this process.

createPayload() Function

createPayload() is a helper function designed to abstract away some of the difficulty seen with building payloads for POST endpoint functions. It works by taking single list(s) as input and combining them together in the format required by the POST endpoints. The function also takes a single string ‘player’ or ‘squad’ to declare which endpoint the payload is being built for.

Users need only to define a single list(s) with the desired parameters and pass those to the function along with a string (either “player” or “squad”) to the endpoint input in the function to construct the payload.

Example Squad Stats Payload

# Squad Payload
q1_f50_tackles <- list( metricCodes = list("TACKLE"), periods = list(1), zones = list("F50"), context = "For", id = "Q1_F50_Tackles" )

q2_f50_tackles <- list( metricCodes = list("TACKLE"), periods = list(2), zones = list("F50"), context = "For", id = "Q2_F50_Tackles" ) 

squadPayload <- createPayLoad(endpoint = "squad", q1_f50_tackles, q2_f50_tackles)

For reference, the above payload being written in the correct structure without using createPayload() (for both the Squad and Player functions) would look like the below:

Example Full Squad Payload

# Squad Payload
squadPayload = list(
   squadMetricRequests = list(
      list(
         metricCodes = list(“TACKLE”),
         periods = list(1),
         zones = list(“F50”),
         context = "For",
         id = "Q1_F50_Tackles"
      ) ,
      list(
         metricCodes = list(“TACKLE”),
         periods = list(2),
         zones = list(“F50”),
         context = "For",
         id = "Q2_F50_Tackles"
      )
   )
)

Example Full Player Payload

# Player Payload
playerPayload = list(
   playerMetricRequests = list(
      list(
         metricCodes = list(“TACKLE”),
         periods = list(1),
         zones = list(“F50”),
         id = "Q1_F50_Tackles"
      ) ,
      list(
         metricCodes = list(“TACKLE”),
         periods = list(2),
         zones = list(“F50”),
         id = "Q2_F50_Tackles"
      )
   )
)

The utility of createPayload() is in removing the requirement to nest & name the lists in the correct way. This leaves the only requirement for the user to be defining as many single list(s) as desired for the payload and select which endpoint the given payload is being built for.

note

metricCodes, periods & zones take inputs as lists, given they can take multiple values.

Parameters & Defaults

The parameters available to be set within each payload are:

• metricCodes - The desired metrics (metric code names ie. “TACKLE” ,“CHAIN_LAUNCH_CB_GB”)
• periods - Match periods (ie. 1, 2, 3, 4)
• zones - Zones (ie. “AM”, “D50”)
• team - Home/Away Team (“home” or “away”)
• context - Match context, a Squad only parameter (ie. “Against”, “For”, “diff”)
• id - User-settable text string for given payload (ie. “Q1_F50_Tackles”)
• lastXseconds - Limits statistics to counting events that occurred in the last X number of seconds. (See R Package Documentation for more information)
• fromPeriodSeconds - Limits statistics to counting events from this point in the period/match. (See R Package Documentation for more information)
• toPeriodSeconds - Limits statistics to counting events to this point in the period/match. (See R Package Documentation for more information)

Each parameter in the player & squad payload(s) has a default value when these values are not explicitly defined. The defaults for each of the parameters are listed below:

• metricCodes - All valid metrics.
• periods - All periods (match to present)
• zones - All zones
• team - Both teams
• context - ‘For’ context– Squad only parameter
• id - Integer for each payload starting from 0.
• lastXseconds - No filter on match period seconds.
• fromPeriodSeconds - No filter on match period seconds.
• toPeriodSeconds - No filter on match period seconds.

Not including/commenting out any parameters in the payload will ensure the defaults are reverted to. Setting the verbose parameter in either getSquadStatsPOST() or getPlayerStatsPOST() will also print to the console a message on which parameters in which payloads are reverting to defaults. See below for an example.

note

The API will not accept empty strings for any parameters, an error will be thrown from the API if this is the case.

Example Parameters

# Squad Payload (‘team’, ‘zones’ & ‘context’ params not included) 
squadPayload = list( 
   squadMetricRequests = list( 
      list( 
         metricCodes = list("TACKLE"), 
         periods = list(1), 
         #zones = list(), 
         #team = "", 
         #context = NA , 
         id = "Q1_Tackles" 
       ) 
   ) 
) 

getSquadStatsPOST(matchId = 120390401, payload = squadPayload, verbose = TRUE)

Console output when verbose = TRUE:

Example Incomplete Payload message

Incomplete Payload 
--> Using defaults for parameters not supplied in the following id: 'Q1_Tackles' - team, zones, context

SQUAD worked examples

Worked Example 1

library(cdAFLAPI)

D50_Tackles_Q1 <- list(
  metricCodes = list("TACKLE") ,
  periods = list(1),
  zones = list("D50") ,
  team = NA ,
  context = NA ,
  lastXSeconds = 300 ,
  id = "D50_Tackles_Q1_Last5"
)

DHalf_Tackles_Q1 <- list(
  metricCodes    = list("TACKLE") ,
  periods    = list(1),
  zones    = list("D50","DM") ,
  team    = NA ,
  context    = NA ,
  fromPeriodSeconds = 300 , 
  toPeriodSeconds   = 600 , 
  id = "DHalf_Tackles_Q1_Min5_Min10"
)

F50_Tackles_Q1 <- list(
  metricCodes = list("TACKLE") ,
  periods = list(1),
  zones = list("F50") ,
  team = NA ,
  context = NA ,
  id = "F50_Tackles_Q1"
)

FHalf_Tackles_Q1 <- list(
  metricCodes = list("TACKLE") ,
  periods = list(1),
  zones = list("F50","AM") ,
  team = NA ,
  context = NA ,
  id = "FHalf_Tackles_Q1"
)

# Combine Payload via createPayload()
squadPayload <- createPayLoad(endpoint = "squad", D50_Tackles_Q1, DHalf_Tackles_Q1, F50_Tackles_Q1, FHalf_Tackles_Q1)

#Output
data <- getSquadStatsPOST(matchId = 120390401, payload = squadPayload, info = T)

Worked Example 2

library(cdAFLAPI)

# Squad Payload
squadPayload <- list(
   squadMetricRequests = list(
      list(
         metricCodes = list("TACKLE") ,
             periods = list(1),
               zones = list("D50") ,
                team = NA ,
             context = NA ,
                  id = "D50_Tackles_Q1"
      ) ,
      list(
         metricCodes = list("TACKLE") ,
             periods = list(1),
               zones = list("D50","DM") ,
                team = NA ,
             context = NA ,
                  id = "DHalf_Tackles_Q1"
      ) ,
      list(
         metricCodes = list("TACKLE") ,
             periods = list(1),
               zones = list("F50") ,
                team = NA ,
             context = NA ,
                  id = "F50_Tackles_Q1"
      ) ,
      list(
         metricCodes = list("TACKLE") ,
             periods = list(1),
               zones = list("F50","AM") ,
                team = NA ,
             context = NA ,
                  id = "FHalf_Tackles_Q1"
      )
   )
)

# Output
data <- getSquadStatsPOST(matchId = 120390401, payload = squadPayload, info = T)

PLAYER worked examples

Worked Example 3

library(cdAFLAPI)

D50_Tackles_Q1 <- list(
  metricCodes = list("GATHER") ,
  periods = list(1),
  zones = list("D50") ,
  team = NA ,
  lastXSeconds = 300 ,
  id = "D50_Gather_Q1_Last5"
)

DHalf_Tackles_Q1 <- list(
  metricCodes    = list("TACKLE") ,
  periods    = list(1),
  zones    = list("D50","DM") ,
  team    = NA ,
  fromPeriodSeconds = 300 , 
  toPeriodSeconds   = 600 , 
  id = "DHalf_Tackles_Q1_Min5_Min10"
)

F50_Tackles_Q1 <- list(
  metricCodes = list("TACKLE") ,
  periods = list(1),
  zones = list("F50") ,
  team = NA ,
  id = "F50_Tackles_Q1"
)

FHalf_Tackles_Q1 <- list(
  metricCodes = list("TACKLE") ,
  periods = list(1),
  zones = list("F50","AM") ,
  team = NA ,
  id = "FHalf_Tackles_Q1"
)

# Combine Payload via createPayload()
squadPayload <- createPayLoad(endpoint = "player", D50_Tackles_Q1, DHalf_Tackles_Q1, F50_Tackles_Q1, FHalf_Tackles_Q1)

#Output
data <- getPlayerStatsPOST(matchId = 120390401, payload = squadPayload, info = T)

Worked Example 4

library(cdAFLAPI)

# Credentials
api_un = ""
api_pw = ""

# Player Payload
playerPayload <- list(
   playerMetricRequests = list(
      list(
         metricCodes = list("TACKLE"),
             periods = list(1),
               zones = list("D50") ,
                team = NA ,
             context = NA ,
                  id = "D50_Tackles_Q1"
      ) ,
      list(
         metricCodes = list("TACKLE") ,
             periods = list(1),
               zones = list("D50","DM") ,
                team = NA ,
             context = NA ,
                  id = "DHalf_Tackles_Q1"
      ) ,
      list(
         metricCodes = list("TACKLE") ,
             periods = list(1),
               zones = list("F50") ,
                team = NA ,
             context = NA ,
                  id = "F50_Tackles_Q1"
      ) ,
      list(
         metricCodes = list("TACKLE") ,
             periods = list(1),
               zones = list("F50","AM") ,
                team = NA ,
             context = NA ,
                  id = "FHalf_Tackles_Q1"
      )
   )
)

# Output
data <- getPlayerStatsPOST(matchId = 120390401, payload = playerPayload, info = T)