documentation fixes

DESCRIPTION

@@ -14,3 +14,11 @@ Suggests:
 Config/testthat/edition: 3
 URL: https://github.com/cole-brokamp/PurpleAir
 BugReports: https://github.com/cole-brokamp/PurpleAir/issues
+Imports: 
+    httr2,
+    purrr,
+    tibble,
+    rlang,
+    cli,
+    dplyr,
+    glue

R/get_sensor_data.R

@@ -4,22 +4,23 @@
 #' 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_key A character that is your PurpleAir API `READ` key
+#' @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`
 #' @export
 #' @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")) {
+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 <-
     purple_air_request(
       resource = "sensors",
       success_code = as.integer(200),
       sensor_index = as.integer(sensor_index),
-      fields = fields
+      fields = fields,
+      read_key = read_key
     )
   resp$sensor$sensor_index <- NULL
   if ("last_seen" %in% names(resp$sensor)) resp$sensor$last_seen <- as.POSIXct.numeric(resp$sensor$last_seen)

R/get_sensors_data.R

@@ -9,16 +9,19 @@
 #' @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_key Your PurpleAir API `READ` key
+#' @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`
 #' @export
 #' @examples
-#' get_sensors_data(x = as.integer(c(175257, 175413)), fields = c("name", "last_seen", "pm2.5_cf_1", "pm2.5_atm"))
-#' get_sensors_data(x = as.integer(c(175257, 175413)), fields = c("name", "pm2.5_cf_1", "pm2.5_atm"), location_type = "outside")
+#' get_sensors_data(x = as.integer(c(175257, 175413)),
+#'   fields = c("name", "last_seen", "pm2.5_cf_1", "pm2.5_atm"))
+#' get_sensors_data(x = as.integer(c(175257, 175413)),
+#'   fields = c("name", "pm2.5_cf_1", "pm2.5_atm"), location_type = "outside")
 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
   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")
+  if (!rlang::is_integer(max_age)) cli::cli_abort("max_age must be an integer")
   location_type <- rlang::arg_match(location_type)
   location_type <- dplyr::case_when(
     location_type == "outside" ~ 0,
@@ -33,9 +36,10 @@ get_sensors_data <- function(x, fields, location_type = c("both", "inside", "out
       resource = "sensors",
       success_code = as.integer(200),
       fields = fields,
+      read_keys = read_keys
     )
   out <-
-    purrr::map(resp$data, setNames, resp$fields) |>
+    purrr::map(resp$data, stats::setNames, resp$fields) |>
     purrr::modify(as.data.frame) |>
     purrr::list_rbind() |>
     tibble::as_tibble()

README.md

@@ -23,6 +23,11 @@ Install the development version of PurpleAir with:
 pak::pak("cole-brokamp/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.
+
 ## Usage
 
 ``` r
@@ -35,16 +40,16 @@ Get the latest data from a single PurpleAir sensor, defined by its
 ``` r
 get_sensor_data(sensor_index = 175413, fields = c("name", "last_seen", "pm2.5_cf_1", "pm2.5_atm"))
 #> $last_seen
-#> [1] "2024-07-05 13:51:43 EDT"
+#> [1] "2024-07-05 14:09:43 EDT"
 #> 
 #> $name
 #> [1] "JN-Clifton,OH"
 #> 
 #> $pm2.5_atm
-#> [1] 4.1
+#> [1] 4.2
 #> 
 #> $pm2.5_cf_1
-#> [1] 4.1
+#> [1] 4.2
 ```
 
 Get the latest data from many PurpleAir sensors, defined by their sensor
@@ -55,8 +60,8 @@ get_sensors_data(x = as.integer(c(175257, 175413)), fields = c("name", "last_see
 #> # A tibble: 2 × 5
 #>   sensor_index last_seen           name          pm2.5_atm pm2.5_cf_1
 #>          <int> <dttm>              <chr>             <dbl>      <dbl>
-#> 1       175257 2024-07-05 13:52:00 Lillard             3.8        3.8
-#> 2       175413 2024-07-05 13:51:43 JN-Clifton,OH       4.1        4.1
+#> 1       175257 2024-07-05 14:10:00 Lillard             3.7        3.7
+#> 2       175413 2024-07-05 14:09:43 JN-Clifton,OH       4.2        4.2
 ```
 
 a geographic bounding box,