Movatterモバイル変換

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:

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

## singlecalpass_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 specifycp_api_uid in the user's.Renviron file in the user's home directory (executeSys.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 specifycp_api_pwd as above.

client_id

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

scope

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

auth_endpoint

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

verbose

IfTRUE, then print http exchanges (to assist with debugging). Defaults toFALSE.

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

forcalpass_query, a single interSegmentKey; forcalpass_query_many, a vector of interSgementKey's. The interSegmentKey's can be created fromcalpass_create_isk.

token

(optional) a token object created fromcalpass_get_token. If this is not specified, thentoken_username,token_password,token_client_id, andtoken_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

IfTRUE, then print http exchanges (to assist with debugging). Defaults toFALSE.

api_call_limit

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

limit_per_n_sec

time frame whereapi_call_limit is applicable to; defaults to 60 seconds.

wait

indicates whether the user is willing to waitlimit_per_n_sec seconds per batch if the number of unique values ininterSegmentKey is greater thanapi_call_limit; defaults toFALSE. The user should set toTRUE if there are more thanapi_call_limit number of calls to be executed.

token_username

(optional, required iftoken is not specified) username passed tocalpass_get_token.

token_password

(optional, required iftoken is not specified) password passed tocalpass_get_token.

token_client_id

(optional, required iftoken is not specified) client_id passed tocalpass_get_token.

token_scope

(optional, required iftoken is not specified) scope passed tocalpass_get_token.

Value

a data frame with columnsinterSegmentKey,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 tokencp_token <- calpass_get_token(username='my_cp_api_uid', password='my_cp_api_pwd')## single runisk <- 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')## multiplefirstname <- 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)