feat: add auth functions and add arg to covidcast

NAMESPACE

@@ -19,6 +19,7 @@ export(flusurv)
 export(fluview)
 export(fluview_clinical)
 export(fluview_meta)
+export(get_auth_key)
 export(gft)
 export(kcdc_ili)
 export(meta)

R/auth.R

@@ -0,0 +1,35 @@
+#' Get the API key
+#'
+#' Get the API key from the environment variable DELPHI_EPIDATA_KEY or getOption("delphi.epidata.key")
+#'
+#' @param verbose Will print the source of the key if TRUE (e.g. options, environment, or config file)
+#' @return The API key
+#'
+#' @export
+get_auth_key <- function() {
+  key <- Sys.getenv("DELPHI_EPIDATA_KEY", unset = "")
+  if (key != "") {
+    return(key)
+  }
+
+  key <- getOption("delphi.epidata.key", default = "")
+  if (key != "") {
+    return(key)
+  }
+
+  rlang::warn(
+    c(
+      "No API key found. You will be limited to non-complex queries and encounter rate limits if you proceed.",
+      "To avoid this, you can get your key [here] and then:",
+      "i" = "set the environment variable DELPHI_EPIDATA_KEY",
+      "i" = "set the option 'delphi.epidata.key'",
+      "",
+      "To save your key for later sessions (and hide it from your code), you can edit your .Renviron file with:",
+      "i" = "usethis::edit_r_environ()"
+    ),
+    use_cli_format = TRUE,
+    .frequency = "regularly",
+    .frequency_id = "delphi.epidata.key"
+  )
+  return("")
+}

R/endpoints.R

@@ -2,7 +2,7 @@
 #'
 #' API docs: https://cmu-delphi.github.io/delphi-epidata/api/afhsb.html
 #'
-#' @param auth string. Authentication token.
+#' @param auth string. Restricted access key (not the same as API key).
 #' @param locations character vector. Locations to fetch (see docs).
 #' @param epiweeks [`epirange`]. Epiweeks to fetch.
 #' @param flu_types string. Flu types to fetch (see docs).
@@ -46,7 +46,7 @@ pvt_afhsb <- function(auth, locations, epiweeks, flu_types) {
 #' call <- pvt_cdc(auth = "yourkey", epirange(20210101, 20210201), "fl,ca")
 #' fetch_tbl(call)
 #' }
-#' @param auth string. Authentication token.
+#' @param auth string. Restricted access key (not the same as API key).
 #' @param epiweeks [`epirange`]. Epiweeks to fetch.
 #' @param locations character vector. Locations to fetch (see docs).
 #' @return [`epidata_call`]
@@ -814,7 +814,7 @@ dengue_nowcast <- function(locations, epiweeks) {
 #' call <- pvt_dengue_sensors(auth = "yourkey", names = "?", locations = "?", epiweeks = epirange(201501, 202001))
 #' fetch_classic(call)
 #' }
-#' @param auth string. Your authentication token.
+#' @param auth string. Restricted access key (not the same as API key).
 #' @param names character vector. The list of names to fetch.
 #' @param locations character vector. The locations to fetch.
 #' @param epiweeks [`epirange`]. The epiweeks to fetch.
@@ -1054,7 +1054,7 @@ fluview_meta <- function() {
 #'   Mutually exclusive with `lag`.
 #' @param lag integer. Optionally, the lag of the issues to fetch. If not set, the most recent issue is returned.
 #'   Mutually exclusive with `issues`.
-#' @param auth string. Optionally, your authentication token.
+#' @param auth string. Optionally, restricted access key (not the same as API key).
 #' @return [`epidata_call`]
 #'
 #' @export
@@ -1146,7 +1146,7 @@ gft <- function(locations, epiweeks) {
 #' call <- pvt_ght(auth = "yourkey", locations = "ca", epiweeks = epirange(201201, 202001), query = "?")
 #' fetch_classic(call)
 #' }
-#' @param auth string. Your authentication token.
+#' @param auth string. Restricted access key (not the same as API key).
 #' @param locations character vector. The locations to be fetched.
 #' @param epiweeks [`epirange`]. The epiweeks to be fetched.
 #' @param query string. The query to be fetched.
@@ -1227,7 +1227,7 @@ kcdc_ili <- function(regions,
 #'
 #' API docs: https://cmu-delphi.github.io/delphi-epidata/api/meta_afhsb.html
 #'
-#' @param auth string. Your authentication token.
+#' @param auth string. Restricted access key (not the same as API key).
 #' @return [`epidata_call`]
 #'
 #' @export
@@ -1241,7 +1241,7 @@ pvt_meta_afhsb <- function(auth) {
 #'
 #' API docs: https://cmu-delphi.github.io/delphi-epidata/api/meta_norostat.html
 #'
-#' @param auth string. Your authentication token.
+#' @param auth string. Restricted access key (not the same as API key).
 #' @return [`epidata_call`]
 #'
 #' @export
@@ -1366,7 +1366,7 @@ nidss_flu <-
 #' )
 #' fetch_classic(call)
 #' }
-#' @param auth string. Your authentication key.
+#' @param auth string. Restricted access key (not the same as API key).
 #' @param location character vector. The locations to fetch.
 #' @param epiweeks [`epirange`]. The epiweeks to fetch.
 #' @return [`epidata_call`]
@@ -1487,7 +1487,7 @@ paho_dengue <- function(regions,
 #' call <- pvt_quidel(auth = "yourkey", epiweeks = epirange(201201, 202001), locations = "hhs1")
 #' fetch_classic(call)
 #' }
-#' @param auth string. Your authentication key.
+#' @param auth string. Restricted access key (not the same as API key).
 #' @param epiweeks [`epirange`]. The epiweeks to fetch.
 #' @param locations character vector. The locations to fetch.
 #' @return [`epidata_call`]
@@ -1522,7 +1522,7 @@ pvt_quidel <- function(auth, epiweeks, locations) {
 #' call <- pvt_sensors(auth = "yourkey", names = "sar3", locations = "nat", epiweeks = epirange(201501, 202001))
 #' fetch_classic(call)
 #' }
-#' @param auth string. Your authentication key.
+#' @param auth string. Restricted access key (not the same as API key).
 #' @param names character vector. The names of the sensors to fetch.
 #' @param locations character vector. The locations to fetch.
 #' @param epiweeks [`epirange`]. The epiweeks to fetch.
@@ -1561,7 +1561,7 @@ pvt_sensors <- function(auth, names, locations, epiweeks) {
 #' call <- pvt_twitter(auth = "yourkey", locations = "CA", epiweeks = epirange(201501, 202001))
 #' fetch_tbl(call)
 #' }
-#' @param auth string. Your authentication key.
+#' @param auth string. Restricted access key (not the same as API key).
 #' @param locations character vector. The locations to fetch.
 #' @param dates [`epirange`]. The dates to fetch. Mutually exclusive with `epiweeks`.
 #' @param epiweeks [`epirange`]. The epiweeks to fetch. Mutually exclusive with `dates`.

R/request.R

@@ -9,14 +9,21 @@ join_url <- function(url, endpoint) {
 #' @importFrom httr RETRY
 do_request <- function(url, params) {
   # don't retry in case of certain status codes
-  res <- httr::RETRY("GET", url,
-    query = params, http_headers,
-    terminate_on = c(400, 401, 403, 405, 414, 500)
+  res <- httr::RETRY("GET",
+    url = url,
+    query = params,
+    terminate_on = c(400, 401, 403, 405, 414, 500),
+    http_headers,
+    httr::authenticate("epidata", get_auth_key())
   )
   if (res$status_code == 414) {
-    res <- httr::RETRY("POST", url,
-      body = params, encode = "form", http_headers,
-      terminate_on = c(400, 401, 403, 405, 414, 500)
+    res <- httr::RETRY("POST",
+      url = url,
+      body = params,
+      encode = "form",
+      terminate_on = c(400, 401, 403, 405, 414, 500),
+      http_headers,
+      httr::authenticate("epidata", get_auth_key())
     )
   }
   res

README.md

@@ -25,6 +25,18 @@ can be still be installed with the old name by specifying
 
 TODO
 
+## API Keys
+
+The Delphi API will soon require a (free) API key for full functionality.
+The `epidatr` client will automatically look for this key in the R option `delphi.epidata.key`
+and then from the environment variable `DELPHI_EPIDATA_KEY`.
+We recommend storing your key in `.Renviron` file, which R will read by default.
+You can do this with `usethis::edit_r_environ()` and there enter `DELPHI_EPIDATA_KEY=<your-key>`.
+An alternative is [the dotenv package](https://github.com/gaborcsardi/dotenv/).
+
+Note that for the time being, the private endpoints (i.e. those prefixed with `pvt`) will require
+a separate key that needs to be passed as an argument.
+
 ## Development Environment
 
 Relevant R commands

tests/testthat/test-auth.R

@@ -0,0 +1,21 @@
+test_that("get_auth_key", {
+  options(delphi.epidata.key = "epidata")
+  expect_equal(get_auth_key(), "epidata")
+  options(delphi.epidata.key = NULL)
+  Sys.setenv(DELPHI_EPIDATA_KEY = "epidata")
+  expect_equal(get_auth_key(), "epidata")
+  Sys.setenv(DELPHI_EPIDATA_KEY = "")
+})
+
+test_that("authenticate", {
+  response <- httr::RETRY("GET", "https://httpbin.org/headers", httr::authenticate("epidata", get_auth_key()))
+  expect_equal(
+    content(response)$headers$Authorization,
+    paste0("Basic ", base64enc::base64encode(charToRaw("epidata:")))
+  )
+  response <- httr::RETRY("GET", "https://httpbin.org/headers", httr::authenticate("epidata", "epidata"))
+  expect_equal(
+    content(response)$headers$Authorization,
+    paste0("Basic ", base64enc::base64encode(charToRaw("epidata:epidata")))
+  )
+})