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
                               )