In joseandresmontes/CharityNavigatoR: Charity Navigator API Client

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Objective

Research More, Search Less. This package was made with the objective of helping organizations with limited sources do more with their time. Unlike other industries, the nonprofit sector is often plague with underdevelopment of database query tools. Charity Navigator has made some headway in alleviating the disparity through the implementation of a robust API that puts its data at the fingertips of data scientists. However, learning the API and how to properly access it in different programming languages can be a barrier for many. CharityClient hopes to provide an accessible, reproducible and reliable package for R users in hopes of inspiring research in the area. Below is an extensive breakdown of the methodology used to access the API.

API Methodology

Authentication

Authentication in Charity Navigator is confirmed with an API ID and key which is passed as part of the request. Two credentials are needed to access the API. These can be acquired at here. There are two plans available as of the time of writing. Free plan Free Plan features basic data access with limits of 1000 hits per day. Content Plan costs 250 after a 30 days free trial and it features full data access with limits of 25000 hits per day. In CharityNavigatoR, these keys are saved into the environment so that they do not need to be reentered in every query.

authentication_params <- list(app_key = Sys.getenv("CHARITY_APP_KEY"),
                     app_id = Sys.getenv("CHARITY_APP_ID"))

Send Request

Requests to the API are sent to the endpoint and with two parameters. 'R user' is set as the user agent for the request and authentication parameters. This is done to provide some context to the API as to who is sending the request.

#URL where requests are sent
charity_endpoint <- "https://api.data.charitynavigator.org/v2/Organizations"

#sets the user
user <- httr::user_agent("R User")

#Combines authentication parameters with user agent in request
response <- httr::GET(charity_endpoint,authentication_params,user)

#View Request Response
response$request


#Specify query parameters to access data from API.
#Two parameters were set here for demonstration purposes.
query_params <- list(app_key = Sys.getenv("CHARITY_APP_KEY"),
                       app_id = Sys.getenv("CHARITY_APP_ID"),
                       pageSize = 10,
                       state = "CA")

#Returns content of query params as a JSON data.frame object
parameter_response <- httr::GET(charity_endpoint, user, query=query_params)
#200 is a successful query
parameter_response$status_code

Data

Data is converted into an R-friendly object that can be accessed via R commands. Below is a summary of the 39 variables in the data set. kniter kable tables are used from here for ease.

#Converts response into a parsable JSON object that is then flattened for easier access.
content <- jsonlite::fromJSON(httr::content(parameter_response, "text"))
data <- data.table::data.table(jsonlite::flatten(content))
knitr::kable(summary(data))

CharityNavigatoR Package

GetOrganizations()

This simple but powerful function applies the aformentioned API methodology in a tight and easy to use function. Name any of the supported arguments (or none at all) to see how easy and fast it accesses the API.

Examples:

# load package
library(CharityNavigatoR)

# No specification aside from limit
knitr::kable(GetOrganizations( limit = 2))

# Relational specification of name
knitr::kable(GetOrganizations("Refresh", limit = 2))

# Combination of relational and assignment specification
knitr::kable(GetOrganizations(state = "NY", name = "Refresh", limit = 2))

# All currently available supported query parameters
knitr::kable(GetOrganizations(name = "Refresh", state = "CA", sizeRange = 1, limit = 2))

joseandresmontes/CharityNavigatoR documentation built on June 5, 2020, 2:34 p.m.