Overview of firstapiR Functions

The Getting Started vignette covered how to use the GetSession() function to create a Session object and how to use that Session object in other firstapiR functions. This vignette provides an overview of the remaining firstapiR functions. For detailed information on each function, type help(function_name) at the console or in the RStudio help view search box.

Simple Functions

There are several functions that take no arguments other than the Session argument.

GetServerStatus(session): Retrieves information about the FIRST API server.
GetSeason(session): Gets information about the season specified in session$season.
GetDistricts(session): Provides a list of FIRST districts.
GetAwardsList(session): Obtains a list and description of awards available to FRC teams.

Functions with Additional Arguments

All other firstapiR functions take at least a few additional arguments. Most of the additional arguments are optional and, usually, only one or two of the additional arguments are used at any one time.

GetEvents(session, event, team, district, exclude_district): Provide information about FRC competition events.
GetTeams(session, team, event, district, state, page): Gets information about FIRST FRC teams.
GetSchedule(session, event, level, team, start, end, expand_cols): Downloads the match schedule for a specific event.
GetHybridSchedule(session, event, level, start, end, expand_cols): Downloads the match schedule, along with results for completed matches.
GetMatchResults(session, event, level, team, match, start, end, expand_cols): Gets the scores for the selected matches.
GetScores(session, event, level, team, match, start, end): Downloads the scoring sheet for each match.
GetAlliances(session, event): Obtains the playoff alliances.
GetRankings(session, event, team, top): Gets the team rankings.
GetAwards(session, event, team): Lists the awards and recipients for an FRC competition.

Function Arguments

Many of the same arguments are used in several different firstapiR functions.

team

The four digit FRC team number.

districts

A code representing a FIRST district. Use GetDistricts() to obtain the district codes that can be used in other firstapiR functions:

library(firstapiR)
sn <- GetSession("username", "key")
districts <- GetDistricts(sn)

event

An event code, such as WAAMV (disctrict competition held at Auburn MountainView High School in Washington State) or PNCMP (Pacific Northwest District Championships). Use the GetEvents() functio to get the event codes:

sn <- GetSession("username", "key")
PNW_events <- GetEvents(sn, district = "PNW")
PNW_events[, c("code", "name")]

##     code                                                          name
## 1  ORORE  PNW District - Clackamas Academy of Industrial Science Event
## 2  ORPHI                                PNW District - Philomath Event
## 3  ORWIL                              PNW District - Wilsonville Event
## 4  PNCMP Pacific Northwest District Championship sponsored by Autodesk
## 5  WAAHS                                   PNW District - Auburn Event
## 6  WAAMV                      PNW District - Auburn Mountainview Event
## 7  WAELL            PNW District - Central Washington University Event
## 8  WAMOU                             PNW District - Mount Vernon Event
## 9  WASNO                             PNW District - Glacier Peak Event
## 10 WASPO                              PNW District - West Valley Event

PNW_events[, c("code", "dateStart")]

##     code           dateStart
## 1  ORORE 2016-03-31T00:00:00
## 2  ORPHI 2016-03-24T00:00:00
## 3  ORWIL 2016-03-10T00:00:00
## 4  PNCMP 2016-04-06T00:00:00
## 5  WAAHS 2016-04-01T00:00:00
## 6  WAAMV 2016-03-03T00:00:00
## 7  WAELL 2016-03-17T00:00:00
## 8  WAMOU 2016-03-18T00:00:00
## 9  WASNO 2016-03-11T00:00:00
## 10 WASPO 2016-03-03T00:00:00

level

Either “playoff” or “qual”. Defaults to “qual”.

start, end, match

Integers specifying the range of matches that will be included in the returned data.

Expanded Columns Option

There are three functions that return data about competition matches and that accept the expand_cols argument:

GetSchedule()
GetHybridSchedule()
GetMatchResults()

By default, expand_cols is FALSE. This causes the function to return a data frame with six rows for every match, with one column for team number, one column for the alliance, etc. This format is preferable for analyzing data. For example, the following code extracts the top eight teams from the data frame by average match score and draws a boxplot for each team.

mr <- firstapiR::GetMatchResults(sn, "PNCMP")

# Put the teams in order by average score
mr$teamNumber <- reorder(mr$teamNumber, -mr$scoreFinal, mean)

# Filter out all but the top 8 teams
top8 <- mr$teamNumber[1:8]
mr8 <- mr[mr$teamNumber %in% top8, ]
mr8$teamNumber <- droplevels(mr8$teamNumber)

# Boxplot the top 8 teams
boxplot(scoreFinal~teamNumber, mr8, las = 2, main = "Qual Scores, Top 8 Teams",
        sub = "2016 PNW District Championships")

Aggregating team performance data would be more difficult if the scores were spread across six different columns instead of contained within a single column.

Setting expand_cols to TRUE puts all data for the match into a single row in the data frame with six different columns for teamNumber, surrogate, final score, etc. This format is useful for displaying an easy to read table:

sched <- firstapiR::GetSchedule(sn, event = "ORPHI", expand_cols = TRUE)

# Display the first 12 rows of the data frame, skipping the first three colums
sched[1:3, 4:17]

##             startTime matchNumber Red1.team Red1.surrogate Red2.team
## 1 2016-03-25T10:45:00           1      5198          FALSE      1318
## 2 2016-03-25T10:52:00           2      2411          FALSE      2521
## 3 2016-03-25T11:02:00           3      4488          FALSE      3636
##   Red2.surrogate Red3.team Red3.surrogate Blue1.team Blue1.surrogate
## 1          FALSE       997          FALSE       3024           FALSE
## 2          FALSE      2811          FALSE       3131           FALSE
## 3          FALSE      3049          FALSE       1983           FALSE
##   Blue2.team Blue2.surrogate Blue3.team Blue3.surrogate
## 1       1359           FALSE        957           FALSE
## 2       3812           FALSE       3574           FALSE
## 3        847           FALSE       4057           FALSE

Pages Argument

There is one firstapiR function, GetTeams(), that accepts the page argument. When requesting data on FRC teams, the FIRST API will split the results into multiple pages if there are more than 65 teams in the response, requiring a separate HTTP request for each page. Users that are requesting the data frame format can ignore the page argument because GetTeams will automatically detect if there are multiple pages in the response, conduct a separate HTTP request for each page, and merge the results into a single data frame. This feature is not available when XML or JSON formats are sepecifed in the Session$format parameter. Users requesting XML or JSON formatted data will have to call GetTeams() for each page of data, incrementing the page argument for each request.

Modified-Since Arguments

There are two additional arguments that can be passed to almost all firstapiR functions (only GetSession() and GetServerStatus() do not accept them). The two arguments, which are always optional, are mod_since and only_mod_since. These two arguments help to reduce the load on the FIRST API server by allowing the server to skip the database query and send only a short HTTP response when the FIRST API server data has not changed since the user last queried the server.

Both of these arguments accept a character vector containing an HTTP formatted date and time string. If the user includes the mod_since argument, and no data has changed on the FIRST API server since the date and time specified in the argument, the FIRST API server will provide an HTTP 304 response with no content. When this happens, irstapiR functions will return a logical character vector with the value NA. Here is an example:

# Create an HTTP date-time string set to midnight GMT yesterday
mod_date <- httr::http_date(as.POSIXct(Sys.Date() - 1))

# Request recently changed data from the server
match_results <- firstapiR::GetMatchResults(sn, event = "PNCMP",
                                            mod_since = mod_date)

# Assuming there have been no updates to the data since yesterday, this
#   returns TRUE
is.na(match_results)

# The value passed to mod_since returned as an attribute, even when the
#   result is NA
print(attr(match_results, "mod_since"))

If the user includes the only_mod_since argument, the FIRST API server will return only the data that has changed since the date and time specified in the only_mod_since argument. In no changes have been made, the FIRST API server provides a 304 response and firstapiR functions return a logical vector set to NA.

# Create an HTTP date-time string set to midnight GMT yesterday
mod_date <- httr::http_date(as.POSIXct(Sys.Date() - 1))

# Request recently changed data from the server
match_results <- firstapiR::GetMatchResults(sn, event = "PNCMP",
                                            only_mod_since = mod_date)

# Assuming there have been no updates to the data since yesterday, this
#   returns TRUE
is.na(match_results)

# The value passed to mod_since returned as an attribute, even when the
#   result is NA
print(attr(match_results, "only_mod_since"))

If the mod_since or only_mod_since arguments are not specified, the corresponding mod_since or only_mod_sinceattribute attached to the return value will be set toNULL`.

Users can keep track of the date and time provided in the last_modified attribute, which corresponds to the most recent date and time that the information changed on the FIRST API server, and use this date and time to request only new data from the server. If a user repeats a firstapiR function call with the same arguments and sets the mod_since or only_mod_since argument to the last_modified attribute value from the intial firstapiR function call, the FIRST API server will return all requested data – the same data that was provided in the first function call. Users who would rather receive a 304 response in this situation should either add at least a second to the last_modified value, or should instead use the time_downloaded attribute value to set the mod_since or only_mod_since arguments.