Title: R Interface to Access CalPASS API
Version: 0.0.3
Description: Implements methods for querying data from CalPASS using its API. CalPASS Plus. MMAP API V1. https://mmap.calpassplus.org/docs/index.html.
Depends: R (≥ 3.4.0)
Imports: httr, dplyr, digest, jsonlite, stringr
License: GPL-3
URL: https://github.com/vinhdizzo/calpassapi
BugReports: https://github.com/vinhdizzo/calpassapi/issues
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.1.0
Suggests: knitr, rmarkdown
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2020-08-06 15:17:15 UTC; vnguyen216
Author: Vinh Nguyen [aut, cre]
Maintainer: Vinh Nguyen <nguyenvq714@gmail.com>
Repository: CRAN
Date/Publication: 2020-08-06 15:30:02 UTC

Create interSegmentKey's for students

Description

Create interSegmentKey's from students' first names, last names, genders, and birthdates

Usage

calpass_create_isk(first_name, last_name, gender, birthdate)

Arguments

first_name

a character vector of students' first names.

last_name

a character vector of students' last names.

gender

a character vector of students' genders. The first character will be used (uppercase'd automatically), and should take on values 'M', 'F', or 'X' (use 'X' for unknown or did not disclosed).

birthdate

a character or numeric vector of birthdates of the form 'yyyymmdd'.

Value

a vector of interSegmentKey's

Author(s)

Vinh Nguyen

Examples

## single
calpass_create_isk(first_name='Jane', last_name='Doe'
 , gender='F', birthdate=20001231)
## data frame
## Not run: 
firstname <- c('Tom', 'Jane', 'Jo')
lastname <- c('Ng', 'Doe', 'Smith')
gender <- c('Male', 'Female', 'X')
birthdate <- c(2001231, 19990101, 19981111)
df <- data.frame(firstname, lastname
  , gender, birthdate, stringsAsFactors=FALSE)
library(dplyr)
df %>%
  mutate(isk=calpass_create_isk(first_name=firstname
    , last_name=lastname
    , gender=gender
    , birthdate
  ))

## End(Not run)

Obtain CalPASS API token

Description

Obtain a token from CalPASS using your API credentials, which should allow access for 60 minutes.

Usage

calpass_get_token(
  username = Sys.getenv("cp_api_uid"),
  password = Sys.getenv("cp_api_pwd"),
  client_id,
  scope,
  auth_endpoint = "https://oauth.calpassplus.org/connect/token",
  verbose = FALSE
)

Arguments

username

API username. For security reasons, the user could specify cp_api_uid in the user's .Renviron file in the user's home directory (execute Sys.getenv('HOME') in R to check path to home directory). That way, the user does not have to hard code the username in their R script. The function uses for the username here by default.

password

API password. The user could specify cp_api_pwd as above.

client_id

parameter needed in the http body in order to obtain a token (unique to username)

scope

parameter needed in the http body in order to obtain a token (unique to username)

auth_endpoint

Authentication endpoint/url, defaults to 'https://oauth.calpassplus.org/connect/token'.

verbose

If TRUE, then print http exchanges (to assist with debugging). Defaults to FALSE.

Value

CalPASS token string

Author(s)

Vinh Nguyen

Examples

## Not run: 
cp_token <- calpass_get_token(username='my_cp_api_uid', password='my_cp_api_pwd'
  , client_id='my_client_id'
  , scope='my_scope'
  )

## End(Not run)

Query data from CalPASS API endpoints

Description

Query data from CalPASS API endpoints for a single interSegmentKey

Usage

calpass_query(
  interSegmentKey,
  token,
  api_url = "https://mmap.calpassplus.org/api",
  endpoint = c("transcript", "placement"),
  verbose = FALSE
)

calpass_query_many(
  interSegmentKey,
  token,
  api_url = "https://mmap.calpassplus.org/api",
  endpoint = c("transcript", "placement"),
  verbose = FALSE,
  api_call_limit = 3200,
  limit_per_n_sec = 3600,
  wait = FALSE,
  token_username,
  token_password,
  token_client_id,
  token_scope
)

Arguments

interSegmentKey

for calpass_query, a single interSegmentKey; for calpass_query_many, a vector of interSgementKey's. The interSegmentKey's can be created from calpass_create_isk.

token

(optional) a token object created from calpass_get_token. If this is not specified, then token_username, token_password, token_client_id, and token_scope should be specified. The credentials approach is preferred for long runs to obtain refreshed tokens (tokens currently are valid for 1 hour).

api_url

defaults to 'https://mmap.calpassplus.org/api', but can be overrode if CalPASS changes the url.

endpoint

the api endpoint to use; defaults to 'transcript'.

verbose

If TRUE, then print http exchanges (to assist with debugging). Defaults to FALSE.

api_call_limit

the number of api calls allowed per limit_per_n_sec; defaults to 150 calls per 60 seconds.

limit_per_n_sec

time frame where api_call_limit is applicable to; defaults to 60 seconds.

wait

indicates whether the user is willing to wait limit_per_n_sec seconds per batch if the number of unique values in interSegmentKey is greater than api_call_limit; defaults to FALSE. The user should set to TRUE if there are more than api_call_limit number of calls to be executed.

token_username

(optional, required if token is not specified) username passed to calpass_get_token.

token_password

(optional, required if token is not specified) password passed to calpass_get_token.

token_client_id

(optional, required if token is not specified) client_id passed to calpass_get_token.

token_scope

(optional, required if token is not specified) scope passed to calpass_get_token.

Value

a data frame with columns interSegmentKey, status_code (the http response code: 200 means student was found, 204 means student was not found, 429 means the api limit was reached and student was not processed, and anything else in the 400's correspond to http errors.)

Functions

Author(s)

Vinh Nguyen

References

MMAP API V1

Examples

## Not run: 
## get access token
cp_token <- calpass_get_token(username='my_cp_api_uid', password='my_cp_api_pwd')

## single run
isk <- calpass_create_isk(first_name='Jane', last_name='Doe'
  , gender='F', birthdate=20001231)
calpass_query(interSegmentKey=isk
  , token=cp_token, endpoint='transcript')
calpass_query(interSegmentKey=isk
  , token=cp_token, endpoint='placement')

## 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)
library(dplyr)
df %>%
  mutate(isk=calpass_create_isk(first_name=firstname
    , last_name=lastname
    , gender=gender
    , birthdate
  )) 
dfResults <- calpass_query_many(interSegmentKey=df$isk
  , token=cp_token
  , endpoint='transcript'
)

## End(Not run)