Merge pull request #628 from cmu-delphi/krivard/covidcast-r-release

Prepare covidcast-R for release 0.5.0

R-packages/covidcast/DESCRIPTION

@@ -1,8 +1,8 @@
 Package: covidcast
 Type: Package
 Title: Client for Delphi's 'COVIDcast Epidata' API
-Version: 0.4.6
-Date: 2023-01-03
+Version: 0.5.0
+Date: 2023-05-23
 Authors@R: 
   c(
     person(given = "Taylor",
@@ -26,6 +26,9 @@ Authors@R:
     person(given = "Pedrito",
            family = "Maynard-Zhang",
            role = "ctb"),
+    person(given = "Kathryn",
+           family = "Mazaitis",
+           role = "aut"),
     person(given = "Alex",
            family = "Reinhart",
            role = c("aut", "cre"),
@@ -59,7 +62,8 @@ Imports:
     purrr,
     rlang,
     sf,
-    tidyr
+    tidyr,
+    xml2
 RoxygenNote: 7.2.3
 Suggests: 
     gridExtra,

R-packages/covidcast/NEWS.md

@@ -1,3 +1,13 @@
+# covidcast 0.5.0
+
+- The package now supports supplying API keys with requests to the COVIDcast
+  Epidata API. Beginning June 21, 2023, the Epidata API server will limit the
+  rate and type of queries made without an API key. See the "API keys" section
+  of `?covidcast_signal` for details on how to obtain and specify an API key.
+  (@krivard, #618)
+
+- Updates to be compatible with changes in dplyr 1.1.0. (@capnrefsmmat, #620)
+
 # covidcast 0.4.5
 
 - Updates to plotting code to be compatible with ggplot2 version 3.4.0.

R-packages/covidcast/R/covidcast.R

@@ -119,6 +119,31 @@ MAX_RESULTS <- 1000000
 #' issued in this case. To see all results, split your query across multiple
 #' calls with different `issues` arguments.
 #'
+#' @section API keys:
+#'
+#' By default, `covidcast_signal()` submits queries to the API anonymously. All
+#' the examples in the package documentation are compatible with anonymous use
+#' of the API, but [there are some limits on anonymous
+#' queries](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html),
+#' including a rate limit. If you regularly query large amounts of data, please
+#' consider [registering for a free API
+#' key](https://api.delphi.cmu.edu/epidata/admin/registration_form), which lifts
+#' these limits. Even if your usage falls within the anonymous usage limits,
+#' registration helps us understand who and how others are using the Delphi
+#' Epidata API, which may in turn inform future research, data partnerships, and
+#' funding.
+#'
+#' If you have an API key, you can use it by setting the `covidcast.auth`
+#' option once before calling `covidcast_signal()` or `covidcast_signals()`:
+#'
+#' ```
+#' options(covidcast.auth = "your_api_key")
+#'
+#' cli <- covidcast_signal(data_source = "fb-survey", signal = "smoothed_cli",
+#'                         start_day = "2020-05-01", end_day = "2020-05-07",
+#'                         geo_type = "state")
+#' ```
+#'
 #' @param data_source String identifying the data source to query. See
 #'   <https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html>
 #'   for a list of available data sources.
@@ -1012,10 +1037,25 @@ covidcast <- function(data_source, signal, time_type, geo_type, time_values,
                            body = params)
   }
 
+  # HTTP 429 Too Many Requests may be API rate-limiting
+  if (httr::status_code(response) == 429 && is.na(auth)) {
+    msg <- xml2::xml_text(xml2::xml_find_all(xml2::read_html(
+        httr::content(response, as = "text", encoding = "utf-8")),
+        "//p"
+        ))
+    abort(c("Rate limit exceeded when fetching data from API anonymously. See the \"API keys\" section of the `covidcast_signal()` documentation for information on registering for an API key.",
+            "i" = "Message from server:",
+            "i" = msg),
+          class = "covidcast_rate_limit",
+          call = parent.frame())
+  }
+
+  # Catch all other kinds of errors
   msg <- "fetch data from API"
   if (is.na(auth)) {
     msg <- paste(msg, "anonymously")
   }
+
   httr::stop_for_status(response, task = msg)
 
   return(httr::content(response, as = "text",

R-packages/covidcast/README.Rmd

@@ -60,12 +60,9 @@ updates.
 ## Usage terms and citation
 
 We request that if you use the covidcast package in your work, or use any of the
-data provided by the COVIDcast Epidata API, that you cite us appropriately:
-
-```{r citation, echo=FALSE, results="asis"}
-print(citation("covidcast"), style = "text")
-```
-
+data provided by the COVIDcast Epidata API, that you cite us using the citations
+given by
+[`citation("covidcast")`](https://cmu-delphi.github.io/covidcast/covidcastR/authors.html#citation).
 See the [COVIDcast Epidata licensing
 documentation](https://cmu-delphi.github.io/delphi-epidata/api/covidcast_licensing.html)
 for information about citing the datasets provided by the API.

R-packages/covidcast/README.md

@@ -55,28 +55,8 @@ other updates.
 
 We request that if you use the covidcast package in your work, or use
 any of the data provided by the COVIDcast Epidata API, that you cite us
-appropriately:
-
-Arnold T, Bien J, Brooks L, Colquhoun S, Farrow D, Grabman J,
-Maynard-Zhang P, Reinhart A, Tibshirani R (2023). *covidcast: Client for
-Delphi’s COVIDcast Epidata API*. R package version 0.4.5,
-<https://cmu-delphi.github.io/covidcast/covidcastR/>.
-
-Reinhart A, Brooks L, Jahja M, Rumack A, Tang J, Agrawal S, Saeed WA,
-Arnold T, Basu A, Bien J, Cabrera ÁA, Chin A, Chua EJ, Clark B,
-Colquhoun S, DeFries N, Farrow DC, Forlizzi J, Grabman J, Gratzl S,
-Green A, Haff G, Han R, Harwood K, Hu AJ, Hyde R, Hyun S, Joshi A, Kim
-J, Kuznetsov A, La Motte-Kerr W, Lee YJ, Lee K, Lipton ZC, Liu MX,
-Mackey L, Mazaitis K, McDonald DJ, McGuinness P, Narasimhan B, O’Brien
-MP, Oliveira NL, Patil P, Perer A, Politsch CA, Rajanala S, Rucker D,
-Scott C, Shah NH, Shankar V, Sharpnack J, Shemetov D, Simon N, Smith BY,
-Srivastava V, Tan S, Tibshirani R, Tuzhilina E, Van Nortwick AK, Ventura
-V, Wasserman L, Weaver B, Weiss JC, Whitman S, Williams K, Rosenfeld R,
-Tibshirani RJ (2021). “An open repository of real-time COVID-19
-indicators.” *Proceedings of the National Academy of Sciences*,
-*118*(51). <doi:10.1073/pnas.2111452118>
-<https://doi.org/10.1073/pnas.2111452118>.
-
+using the citations given by
+[`citation("covidcast")`](https://cmu-delphi.github.io/covidcast/covidcastR/authors.html#citation).
 See the [COVIDcast Epidata licensing
 documentation](https://cmu-delphi.github.io/delphi-epidata/api/covidcast_licensing.html)
 for information about citing the datasets provided by the API.