covidcast package updates for API keys #618

krivard · 2023-03-03T21:59:22Z

Preparing changes to be released before rollout of Epidata API Keys.

This PR makes the following changes:

Python client
- add use_api_key as a pass-through to the delphi-epidata python client, which handles keys through a class member
- update package documentation overview warning (this turned into a wall of text, but I'd like to retain the appeal to register if we can -- open to ideas)
- update package documentation getting-started with instructions for applying an API key to requests
- update documentation build process & instructions, which had lost sync
R client
- add Authorization:Bearer headers using getOptions
- update package documentation getting-started with instructions for applying an API key to requests
- update package documentation multi-signals example to not require an API key to replicate

Checklist from draft mode

Add documentation for setting API key in the R client
Add documentation for setting API key in the Python client
Change R vignettes to be anonymous-request -compliant (multi-signals.Rmd; all others checked exhaustively)
Check Python docs to be anonymous-request -compliant
Rebuild R docs -- not committing them here since that seems to be part of the release process; R docs preview
Rebuild Sphinx docs -- not committing them here; Python docs preview

krivard

Fill constants in python docs, update language

R-packages/covidcast/R/covidcast.R

Python-packages/covidcast-py/covidcast/covidcast.py

Python-packages/covidcast-py/docs/changelog.rst

capnrefsmmat

A few small tweaks to make, I think

R-packages/covidcast/vignettes/covidcast.Rmd

Python-packages/covidcast-py/docs/changelog.rst

capnrefsmmat · 2023-05-15T14:39:36Z

Python-packages/covidcast-py/docs/getting_started.rst

@@ -104,6 +104,15 @@ May 1st were updated on May 23rd based on new data, giving a ``lag`` of 22 days.
 See the :py:func:`covidcast.signal` documentation for details on the returned
 data frame.

+By default, this package submits queries to the API anonymously. If you have an
+API key, you can use it with this package by calling
+:py:func:`covidcast.use_api_key`, then call fetch functions as normal:


This will cross-reference with a link to the covidcast.use_api_key docs, but those docs aren't actually included in Sphinx anywhere. Probably we want to add an "API keys" section to signals.rst, containing .. autofunction: covidcast.use_api_key, right?

capnrefsmmat · 2023-05-15T14:41:13Z

Python-packages/covidcast-py/docs/index.rst

+.. warning :: By default, this package 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>`_
+   which do not apply if you use an API key to authenticate your queries. If you
+   regularly or frequently use our system, please consider `registering for a
+   free API key <https://forms.gle/hkBr5SfQgxguAfEt7>`_ even if your usage falls
+   within the anonymous usage limits. API key usage helps us understand who and
+   how others are using our Delphi Epidata API, which may in turn inform our
+   future research, data partnerships, and funding. As we are a research group,
+   our server resources are limited and cannot support high-volume interactive
+   use (with or without an API key). If you use data from the COVIDcast Epidata
+   API to power a public product, dashboard, app, or other service, please
+   download the data you need and store it centrally rather than making API
+   requests for every user.


Once we have covidcast.use_api_key in signals.rst, we could edit this to refer to that, so people see in one place (a) how to register and (b) how to use the keys. Currently this message says how to register but not how to actually use the key you get

Done; also split off "please don't hammer our server" into a separate paragraph

capnrefsmmat · 2023-05-15T14:45:21Z

R-packages/covidcast/R/covidcast.R

-  httr::stop_for_status(response, task = "fetch data from API")
+  msg <- "fetch data from API"
+  if (is.na(auth)) {
+    msg <- paste(msg, "anonymously")


In the future, if we want to nag people harder to register, we could use rlang::inform with .frequency = "once" so they get a message once per session telling them they ought to register. It could be guarded by the same is.na(auth) here

hmmm we aren't nagging anyone anywhere else, but this is good to keep in mind for the future

Co-authored-by: Alex Reinhart <areinhar@stat.cmu.edu>

capnrefsmmat

Looks good to me, modulo one tiny nitpick

Python-packages/covidcast-py/docs/signals.rst

Co-authored-by: Alex Reinhart <areinhar@stat.cmu.edu>

krivard added covidcast R package covidcast Python package labels Mar 3, 2023

krivard force-pushed the krivard/covidcast-update-api-keys branch from 448b8d3 to 34b6b15 Compare March 29, 2023 14:35

Python client API key support

c6b43aa

krivard force-pushed the krivard/covidcast-update-api-keys branch from 34b6b15 to ce11af0 Compare April 25, 2023 19:37

krivard commented May 3, 2023

View reviewed changes

R-packages/covidcast/R/covidcast.R Outdated Show resolved Hide resolved

Python-packages/covidcast-py/covidcast/covidcast.py Outdated Show resolved Hide resolved

krivard force-pushed the krivard/covidcast-update-api-keys branch 2 times, most recently from 0442d9a to a630c87 Compare May 9, 2023 19:21

krivard added 7 commits May 9, 2023 15:30

R covidcast client API key support

9fe3c73

Pin pandas before v2

6a72e1f

Fill constants in python docs, update language

15a53d9

Add api keys to R package documentation

63b6426

Better stop for status handling in R client

f9a6d8a

Update Sphinx docs for python client

b9562b4

Fix Sphinx documentation build instructions

178b283

krivard force-pushed the krivard/covidcast-update-api-keys branch from a630c87 to 178b283 Compare May 9, 2023 19:30

krivard commented May 9, 2023

View reviewed changes

Python-packages/covidcast-py/docs/changelog.rst Show resolved Hide resolved

krivard marked this pull request as ready for review May 9, 2023 19:41

krivard requested review from chinandrew and capnrefsmmat as code owners May 9, 2023 19:41

krivard requested a review from nmdefries May 15, 2023 13:24

capnrefsmmat requested changes May 15, 2023

View reviewed changes

krivard and others added 2 commits May 15, 2023 13:58

Suggested changes from code review

c320433

Co-authored-by: Alex Reinhart <areinhar@stat.cmu.edu>

Add API keys header to R client covidcast docs

71de5cd

Co-authored-by: Alex Reinhart <areinhar@stat.cmu.edu>

krivard requested a review from capnrefsmmat May 15, 2023 18:11

capnrefsmmat approved these changes May 15, 2023

View reviewed changes

Python-packages/covidcast-py/docs/signals.rst Outdated Show resolved Hide resolved

Sentence case ftw

a44690d

Co-authored-by: Alex Reinhart <areinhar@stat.cmu.edu>

krivard merged commit 5900ee6 into main May 15, 2023
3 checks passed

krivard deleted the krivard/covidcast-update-api-keys branch May 15, 2023 21:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

covidcast package updates for API keys #618

covidcast package updates for API keys #618

krivard commented Mar 3, 2023 •

edited

krivard left a comment

capnrefsmmat left a comment

capnrefsmmat May 15, 2023

krivard May 15, 2023

capnrefsmmat May 15, 2023

krivard May 15, 2023

capnrefsmmat May 15, 2023

krivard May 15, 2023

capnrefsmmat left a comment

covidcast package updates for API keys #618

covidcast package updates for API keys #618

Conversation

krivard commented Mar 3, 2023 • edited

krivard left a comment

Choose a reason for hiding this comment

capnrefsmmat left a comment

Choose a reason for hiding this comment

capnrefsmmat May 15, 2023

Choose a reason for hiding this comment

krivard May 15, 2023

Choose a reason for hiding this comment

capnrefsmmat May 15, 2023

Choose a reason for hiding this comment

krivard May 15, 2023

Choose a reason for hiding this comment

capnrefsmmat May 15, 2023

Choose a reason for hiding this comment

krivard May 15, 2023

Choose a reason for hiding this comment

capnrefsmmat left a comment

Choose a reason for hiding this comment

krivard commented Mar 3, 2023 •

edited