The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

The calpassapi R package contains functions that help a user query data using CalPASS's API.

Install Package

# From CRAN (Official)
## install.packages('calpassapi')

# From github (Development)
## devtools::install_github('vinhdizzo/calpassapi')

Load Packages

library(calpassapi)
library(dplyr) # Ease in manipulations with data frames

Setup

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.

Obtain access 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.

Create interSegmentKey's for each student

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"

Query data from CalPASS

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'
                           )

Multiple batches (when there are many interSegmentKey's)

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
                           )

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.