documentation and formatting

R/check_api_key.R

@@ -1,12 +1,15 @@
-#' check purple air api key
+#' Check Purple Air API Key
 #'
 #' Use the PurpleAir API to validate your Purple Air API Key.
-#' Find more details on this function at https://api.purpleair.com/#api-keys-check-api-key
+#' Find more details on this function at https://api.purpleair.com/#api-keys-check-api-key.
+#' Storing your key in the environment variable `PURPLE_AIR_API_KEY` is safer than storing it
+#' in source code and is used by default in each PurpleAir function.
 #' @param purple_air_api_key A character that is your PurpleAir API `READ` key
-#' @returns if the key is valid, a message is emitted and the input is invisibly returned;
+#' @returns If the key is valid, a message is emitted and the input is invisibly returned;
 #' invalid keys will throw an R error which utilizes information from the underlying http error
-#' to inform the user
+#' to inform the user.
 #' @export
+#' @seealso get_organization_data
 #' @examples
 #' check_api_key()
 #' try(check_api_key("foofy"))
@@ -18,7 +21,11 @@ check_api_key <- function(purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY"))
   ) |>
     httr2::req_perform() |>
     httr2::resp_body_json()
-  # TODO add check that is must be a `READ` type key?
-  cli::cli_alert_success("Using valid '{resp$api_key_type}' key with version {resp$api_version} of the PurpleAir API on {as.POSIXct(resp$time_stamp)}")
+  cli::cli_alert_success(c(
+    "Using valid '{resp$api_key_type}' key ",
+    "with version {resp$api_version} ",
+    "of the PurpleAir API on ",
+    as.POSIXct(resp$time_stamp)
+  ))
   return(invisible(purple_air_api_key))
 }

R/get_organization_data.R

@@ -1,10 +1,11 @@
-#' get organization data
+#' Get Organization Data
 #'
 #' Use the PurpleAir API to retrieve information for the organization containing the provided api_key
 #' Find more details on this function at https://api.purpleair.com/#api-organization-get-organization-data
 #' @param purple_air_api_key A character that is your PurpleAir API `READ` key
-#' @returns a list of organization info
+#' @returns A list of organization info
 #' @export
+#' @seealso check_api_key
 #' @examples
 #' get_organization_data()
 get_organization_data <- function(purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY")) {

R/get_sensor_data.R

@@ -1,17 +1,21 @@
-#' get sensor data
+#' Get Sensor Data
 #'
 #' Retrieves the latest data of a single sensor matching the provided `sensor_index`.
 #' Find more details on sensor fields at https://api.purpleair.com/#api-sensors-get-sensor-data.
 #' @param sensor_index Integer (or numeric, character object coerceable to integer) `sensor_index`
 #' @param fields A character vector of which 'sensor data fields' to return
 #' @param purple_air_api_key A character that is your PurpleAir API `READ` key
 #' @param read_key A character key required to read data from private devices
-#' @returns a list of sensor data, named by the provided `fields`
+#' @returns A list of sensor data, named by the provided `fields`
 #' @export
+#' @seealso get_sensors_data get_sensor_history
 #' @examples
 #' get_sensor_data(sensor_index = 175413, fields = c("name", "last_seen", "pm2.5_cf_1", "pm2.5_atm"))
 #' get_sensor_data(sensor_index = "175413", fields = c("name", "last_seen", "pm2.5_cf_1", "pm2.5_atm"))
-get_sensor_data <- function(sensor_index, fields, purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY"), read_key = NULL) {
+get_sensor_data <- function(sensor_index,
+                            fields,
+                            purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY"),
+                            read_key = NULL) {
   if (!rlang::is_integer(as.integer(sensor_index))) cli::cli_abort("sensor_index must be an integer")
   if (!rlang::is_character(fields)) cli::cli_abort("fields must be a character")
   resp <-

R/get_sensors_data.R

@@ -1,18 +1,19 @@
-#' get sensors data
+#' Get Sensors Data
 #'
 #' Retrieves the latest data of multiple sensors matching the provided parameters.
 #' Find more details on sensor fields at https://api.purpleair.com/#api-sensors-get-sensors-data.
 #' @param x an input object used to define multiple sensors:
-#' - integer (or numeric or character) vector will select sensors based on `sensor_index` (API: `show_only`)
-#' - st_bbox object will select sensors geographically (API: `nwlat`, `nwlon`, `selat`, `selon`)
-#' - POSIXct object will select sensors modified since then (API: `modified_since`)
+#' - an integer (or numeric or character) vector will select sensors based on `sensor_index` (API: `show_only`)
+#' - a st_bbox object will select sensors geographically (API: `nwlat`, `nwlon`, `selat`, `selon`)
+#' - a POSIXct object will select sensors modified since the given time (API: `modified_since`)
 #' @param fields A character vector of which 'sensor data fields' to return
 #' @param location_type character; restrict to only "outside" or "inside" sensors (Outside: 0, Inside: 1)
 #' @param max_age integer; filter results to only include sensors modified or updated within the last number of seconds
 #' @param purple_air_api_key Your PurpleAir API `READ` key
-#' @param read_keys TODO A character vector of keys required to read data from private devices
-#' @returns a list of sensor data, named by the provided `fields`
+#' @param read_keys A character vector of keys required to read data from private devices
+#' @returns A list of sensor data, named by the provided `fields`
 #' @export
+#' @seealso get_sensor_data
 #' @examples
 #' # get sensors data by integer, numeric, or character vector of `sensor_index`
 #' get_sensors_data(
@@ -34,8 +35,12 @@
 #'   get_sensors_data(fields = c("name"))
 #' # sensors modified in the last 60 seconds
 #' get_sensors_data(as.POSIXct(Sys.time()) - 60, fields = "name")
-get_sensors_data <- function(x, fields, location_type = c("both", "inside", "outside"), max_age = as.integer(604800), purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY"), read_keys = NULL) {
-  # TODO support multiple read keys
+get_sensors_data <- function(x,
+                             fields,
+                             location_type = c("both", "inside", "outside"),
+                             max_age = as.integer(604800),
+                             purple_air_api_key = Sys.getenv("PURPLE_AIR_API_KEY"),
+                             read_keys = NULL) {
   if (!rlang::is_character(fields)) cli::cli_abort("fields must be a character")
   if (!rlang::is_integer(max_age)) cli::cli_abort("max_age must be an integer")
   location_type <- rlang::arg_match(location_type)
@@ -98,7 +103,5 @@ get_sensors_data <- function(x, fields, location_type = c("both", "inside", "out
     purrr::list_rbind() |>
     tibble::as_tibble()
   if ("last_seen" %in% resp$fields) out$last_seen <- as.POSIXct.numeric(out$last_seen)
-  # TODO return metadata how?
-  md <- purrr::discard_at(resp, c("fields", "data"))
   return(out)
 }

R/purple_air_request.R

@@ -26,5 +26,3 @@ purple_air_request <- function(purple_air_api_key = Sys.getenv("PURPLE_AIR_API_K
   if (resource == "sensor_history") req <- httr2::req_url_path_append(req, "sensors", sensor_index, "history")
   return(req)
 }
-
-# https://api.purpleair.com/#api-sensors-get-sensor-data

README.Rmd

@@ -16,7 +16,7 @@ knitr::opts_chunk$set(
 # PurpleAir
 
 <!-- badges: start -->
-[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
+[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
 [![CRAN status](https://www.r-pkg.org/badges/version/PurpleAir)](https://CRAN.R-project.org/package=PurpleAir)
 [![R-CMD-check](https://github.com/cole-brokamp/PurpleAir/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/cole-brokamp/PurpleAir/actions/workflows/R-CMD-check.yaml)
 <!-- badges: end -->
@@ -41,7 +41,7 @@ pak::pak("cole-brokamp/PurpleAir")
 library(PurpleAir)
 ```
 
-Querying data from the PurpleAir API requires a free [PurpleAir Developer API key](https://develop.purpleair.com/sign-in?redirectURL=%2Fdashboards%2Fkeys) linked to a Google account. Functions in the package each take a `purple_air_api_key` argument or your key can be stored in an environment variable called `PURPLE_AIR_API_KEY`).  To check your key, use:
+Querying data from the PurpleAir API requires a free [PurpleAir Developer API key](https://develop.purpleair.com/sign-in?redirectURL=%2Fdashboards%2Fkeys) linked to a Google account. Functions in the package each take a `purple_air_api_key` argument or your key can be stored in an environment variable called `PURPLE_AIR_API_KEY`.  To check your key, use:
 
 ```{r}
 check_api_key(Sys.getenv("PURPLE_AIR_API_KEY"))
@@ -61,7 +61,7 @@ get_sensors_data(x = as.integer(c(175257, 175413)),
                  fields = c("name", "last_seen", "pm2.5_cf_1", "pm2.5_atm"))
 ```
 
-a geographic bounding box,
+a geographic [bounding box](http://bboxfinder.com),
 
 ```{r}
 sf::st_bbox(