calpass_query {calpassapi}

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

• calpass_query_many: Query data from CalPASS API endpoints with a vector of interSegmentKey's. The number of rows returned corresponds to the number of unique interSegmentKey's.

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)