The calpassapi
R package contains functions that help a user query data using CalPASS's API.
# From CRAN (Official)
## install.packages('calpassapi')
# From github (Development)
## devtools::install_github('vinhdizzo/calpassapi')
library(calpassapi)
library(dplyr) # Ease in manipulations with data frames
If the user does not want to expose their CalPASS API username and password in their R script, then it is recommended that the user specify their credentials in their .Renviron
file in their home directory (execute Sys.getenv('HOME')
in R to determine the R home directory) as follows:
cp_api_uid='my_username'
cp_api_pwd='my_password'
R will automatically load these environment variables at start up and the user will not have to specify username
and password
in calpass_get_token
.
First we need to authenticate with CalPASS using our credentials in order to obtain a token that will allow us to query data from the API.
cp_token <- calpass_get_token(username='my_cp_api_uid', password='my_cp_api_pwd', client_id='my_client_id', scope='my_scope')
# cp_token <- calpass_get_token(client_id='my_client_id', scope='my_scope') ## if cp_api_uid and cp_api_pwd are set in .Renviron
This token will be used in calpass_query
and calpass_query_many
in the token
argument.
To obtain information for a particular student, we need to convert the student's first name, last name, gender, and birthdate into an interSegmentKey
, a key that allows the API to look up a student.
# single
isk <- calpass_create_isk(first_name='Jane', last_name='Doe'
, gender='F', birthdate=20001231)
isk
## [1] "D04ADB733A5E2F09744F6BB581A712D634702A181A020ED59B083DCE412E788101EDBA6CAEE8F7A90DF20B56D7519CF1699D167891D182076E34A27F7166F672"
# multiple
firstname <- c('Tom', 'Jane', 'Jo')
lastname <- c('Ng', 'Doe', 'Smith')
gender <- c('Male', 'Female', 'X')
birthdate <- c(20001231, 19990101, 19981111)
df <- data.frame(firstname, lastname
, gender, birthdate, stringsAsFactors=FALSE)
df <- df %>%
mutate(isk=calpass_create_isk(first_name=firstname
, last_name=lastname
, gender=gender
, birthdate
))
df$isk
## [1] "5DFEBA29144043D4B504BDAC0F4831DC7AE48C61F67164535E89D577FA46156089A96A34F8D82A7281CB035E339999AE38C3C159738D7FAA53E708F63E2C55A3"
## [2] "B99037E0B8AEBBE4C9F5AA0A7C67813D5628D940972D4BBC0980D1BFF587C8D0BC716784004693E087E9E6D9889B610D840EAA72285B64779A73C916CD1934FC"
## [3] "858C66FA1B48020F8CB8734A7596666DF607C91DFA6BA7325C86BD029BB44AAD0A3D0D64283D1F1C0AA14D68B4820B39889848D47C5B3A85A177426F80349824"
After we have the interSegmentKey
's, we can now query data from CalPASS.
## single
calpass_query(interSegmentKey=isk
, token=cp_token, endpoint='transcript')
## multiple
dfResults <- calpass_query_many(interSegmentKey=df$isk
, token=cp_token
, endpoint='transcript'
)
## can specify credentials
dfResults <- calpass_query_many(interSegmentKey=df$isk
, endpoint='transcript'
, token_username='my_username'
, token_password='my_password'
, token_client_id='my_client_id'
, token_scope='my_scope'
)
The CALPASS API currently has a limit of 3200 calls per hour (3600 seconds). These are specified by default in the api_call_limit
and limit_per_n_sec
arguments in calpass_query_many
. If the user has a need beyond these limits, or if the user would like to break the calls into batches, then the user should specify wait=TRUE
, and calpass_query_many
will break the calls into batches of api_call_limit
calls.
## batches
dfResults <- calpass_query_many(interSegmentKey=df$isk
, token=cp_token
, endpoint='transcript'
, api_call_limit=2 ## batches of 2
, limit_per_n_sec=10 ## every 10 seconds
, wait=TRUE
)