vignettes/articles/Working_with_PurpleAir_API_Keys.Rmd
Working_with_PurpleAir_API_Keys.RmdThe AirSensor2 package allows users to work with the PurpleAir API which requires API keys. This document describes how to automate work with private API keys without including them in a code repository where they might be seen by others.
The PurpleAir API is described at: https://api.purpleair.com/
When working with PurpleAir data, you should be aware of the following:
PurpleAir maintains a community forum with a page dedicated to obtaining an API Key: https://community.purpleair.com/t/how-to-obtain-an-api-key
global_vars.R file
It is useful to create a file where all API keys and passwords are
kept. I recommend keeping this information in a file named
global_vars.R which can be sourced at the RStudio prompt or
at the beginning of a script. Here is an example:
# global_vars.R file
# ----- PurpleAir API keys ----------------------------------------------------
PurpleAir_API_READ_KEY <- "********-2A00-11EB-A8CD-42010A800126" # associated.email@gmail.com
PurpleAir_API_WRITE_KEY <- "********-2A00-11EB-A8CD-42010A800126" # associated.email@gmail.com.gitignore file
To avoid uploading your private API keys to GitHub where they might
be seen by others, you should create/modify the repository
.gitignore file so that it looks something like this:
# .gitignore file
# History files
.Rhistory
.Rapp.history
# Session Data files
.RData
# User-specific files
.Ruserdata
# Example code in package build process
*-Ex.R
# Output files from R CMD build
/*.tar.gz
# Output files from R CMD check
/*.Rcheck/
# RStudio files
.Rproj.user/
# produced vignettes
vignettes/*.html
vignettes/*.pdf
# OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3
.httr-oauth
# knitr and R markdown default cache directories
*_cache/
/cache/
# Temporary files created by R markdown
*.utf8.md
*.knit.md
# R Environment Variables
.Renviron
# ----- Local customization -----
# API Keys
global_vars.RThe AirSensor2 package maintains an internal set of
API keys which users can set using setAPIKey(). These keys
will be remembered for the duration of an R session. In functions that
accept an API key argument, if the passed in API key is
NULL, code will look up a specific named API key to see if
that key has been set globally. Setting keys globally is a convenience
that simplifies the scripts written by end users.
Currently supported API keys and associated functions include:
"PurpleAir-read" – PurpleAir api_key used in
pas_downloadParseRawData()
pat_downloadParseRawData(), pat_create()."Clarity-read" – Clarity api_key used in
Clarity_createOpenMonitor(),
Clarity_createOpenSynoptic().Scripts can take advantage of this as seen below:
# AirSensor2 package
library(AirSensor2)
# Set user's PurpleAir_API_READ_KEY
source('global_vars.R')
setAPIKey("PurpleAir-read", PurpleAir_API_READ_KEY)
# Initialize spatial datasets
initializeMazamaSpatialUtils()
...From this point on in the R session, all AirSensor2 functions that need to pull data from the PurpleAir API will send the appropriate API key and everything should work.
Best of luck working with new PurpleAir API!