PurpleAir provides access to the observations from their network of low-cost PM2.5 monitors through a points-based API system. New accounts start with 1M points, and each request has a cost from 1-5 points plus the number of rows times the total column cost (which depends on the column, typically 1-2 points per column). Point can be purchased on develop.purpleair.com and cost less if buying in bulk.
For more information, see: api.purpleair.com
In order to retrieve these data you must:
make an account on develop.purpleair.com (a google account is required, which can be made using any email)
create a new project, click on it after it is created
add two API keys, 1 for reading (getting data), 1 for writing (making groups of sensors)
(Optional) open your .Renviron for editing (you can use
usethis::edit_r_environ("project")after installing the usethis package)(Optional) add your keys on 2 seperate lines in this format:
purpleair_api_read = "YOUR-API-KEY-HERE"(Optional) refer to keys using
read_key = Sys.getenv("purpleair_api_read")to keep your API key secure
purpleair_api() requires either a read or write key (depending on what you are trying to do), a channel name to make a request to,
and (depending on the request type you want to make) a named list of parameters.
See api.purpleair.com for which parameters are avalailable for each request type.
Based on the provided channel/parameters, the request and estimated points cost will be displayed,
and the request will be made if desired. Set quiet to TRUE to silence this and always run the request
(caution, some requests may cost a lot of points)
Usage
purpleair_api(
read_key = NULL,
write_key = NULL,
channel,
parameters = NULL,
quiet = FALSE,
estimate_cost = TRUE
)Arguments
- read_key
(Optional) A single character value of your PurpleAir API read key (see develop.purpleair.com). If NULL, write_key must be provided.
- write_key
(Optional) A single character value of your PurpleAir API write key (see develop.purpleair.com). If NULL, read_key must be provided.
- channel
A single character value indicating what API channel to use (Currently supported: keys, organization, sensors, groups)
- parameters
(Optional) A named list containing paramaters to be supplied to the API request (see api.purpleair.com).
- quiet
(Optional) A single logical (TRUE or FALSE) value indicating if non-critical messages/warnings should be silenced.
- estimate_cost
(Optional) A single logical (TRUE or FALSE) value indicating if the cost of the request should be estimated. Default is TRUE.
Value
If channel either "keys" or "organization", or invalid/missing parameters, then a list with the request results If sensors or groups channel, then a tibble with the data returned from the request
See also
Other Data Collection:
get_abgov_data(),
get_abgov_stations(),
get_airnow_data(),
get_airnow_stations(),
get_bcgov_data(),
get_bcgov_stations()
Other Canadian Air Quality:
CAAQS()
Examples
if (FALSE) { # \dontrun{
read_key <- Sys.getenv("purpleair_api_read")
write_key <- Sys.getenv("purpleair_api_write")
parameters <- list( # see api.purpleair.com for more
nwlat = 53.93, nwlng = -122.77,
selat = 53.9, selng = -122.73,
fields = "temperature",
sensor_index = 198385,
start_timestamp = Sys.time() - lubridate::hours(1)
)
# Get Sensors Data
# test = purpleair_api(read_key = read_key, channel = "sensors",
# parameters = parameters[1:5])
# Get Sensor Data
# test = purpleair_api(read_key = read_key, channel = "sensors",
# parameters = parameters[5:6])
# Get Sensor History
# test = purpleair_api(read_key = read_key, channel = "sensors",
# parameters = parameters[5:7])
} # }