diff --git a/docs/api/README.md b/docs/api/README.md index f2be98f34..add09fd98 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -1,6 +1,6 @@ --- title: Other Endpoints (COVID-19 and Other Diseases) -nav_order: 2 +nav_order: 3 has_children: true --- diff --git a/docs/api/api_keys.md b/docs/api/api_keys.md new file mode 100644 index 000000000..421135023 --- /dev/null +++ b/docs/api/api_keys.md @@ -0,0 +1,64 @@ +--- +title: API Keys +nav_order: 1 +has_children: true +--- + +# Epidata API Keys + +Anyone may access the Epidata API anonymously without providing any personal +data. Anonymous API access is subject to the following restrictions: + +1. public datasets only +1. rate-limited to 100 requests per hour +1. only two parameters may have multiple selections + +For example, a query for three signals on one date across all counties can be +submitted anonymously, but a query for three signals on a period of four weeks +across all counties requires an API key. + +An API key is a pseudonymous access token that grants privileged access to the +Epidata API. You can request an API key by +[registering with us](https://forms.gle/hkBr5SfQgxguAfEt7). +Privileges of registration may include: + +1. restricted-access datasets +1. no rate limit +1. no limit on multiple selections + +We require an email address for all registrations so that we can contact you to +resolve problems with excessive or abnormal usage patterns. Any additional +personal information you provide to us at registration will be much appreciated, +because it will help us understand what our data is used for and inform our +plans and priorities, but is voluntary. For more information on how we use and +store the information you provide us at registration time, see our +[privacy statement](api/privacy_statement.md). + +## Usage + +If you choose to [register for an API key](https://forms.gle/hkBr5SfQgxguAfEt7), +there are several ways to use your key to authenticate your requests: + +### Via request parameter + +The request parameter “api_key” can be used to pass the API key to the server. +Example: + + http://delphi.cmu.edu/epidata/covidcast/meta?api_key=your_api_key_here + +### Via Basic Authentication + +Another method is using the HTTP basic authorization header with the username +"epidata" and the API key as the password. Example: + +``` +curl -u 'epidata:your_api_key_here' https://delphi.cmu.edu/epidata/covidcast/meta +``` + +### Via Bearer Token + +Another method is providing the key in a bearer token header. Example: + +``` +curl -H 'Authorization: Bearer your_api_key_here' https://delphi.cmu.edu/epidata/covidcast/meta +``` diff --git a/docs/api/covidcast.md b/docs/api/covidcast.md index ddfce9c06..c1cb625a2 100644 --- a/docs/api/covidcast.md +++ b/docs/api/covidcast.md @@ -1,7 +1,7 @@ --- title: COVIDcast Main Endpoint has_children: true -nav_order: 1 +nav_order: 2 --- # COVIDcast Epidata API diff --git a/docs/api/privacy_statement.md b/docs/api/privacy_statement.md new file mode 100644 index 000000000..002367931 --- /dev/null +++ b/docs/api/privacy_statement.md @@ -0,0 +1,55 @@ +--- +title: Privacy Statement +parent: API Keys +--- + +# Delphi Privacy Statement + +Anyone may access the Epidata API anonymously without providing any personal +data. + +Some features of the API are only available by registering for an API key. We +require an email address for all registrations so that we can contact you to +resolve problems with excessive or abnormal usage patterns. Any additional +personal information you provide to us at registration will be much appreciated, +because it will help us understand what our data is used for and inform our +plans and priorities, but is voluntary. + +You may also choose to share personal information with us to participate in user +surveys. + +We log information about API traffic including the query parameters, API key, +and source IP address for each request. We retain these logs for a period of not +longer than five years. We use this information for the following +purposes: + +* to monitor the responsiveness of the API service +* to monitor the relative popularity of different data and features, alone and + in concert with user survey results +* to identify excessive or abnormal usage patterns which may harm our system + +The logs are only available to members of our operations team, and are expunged +at or before they reach five years in age. + +If you provide us with your email address, we will only use it to contact you in +the following scenarios: + +* you asked a question in a user survey and we have an answer for you +* we make improvements or other changes to the Epidata API service +* the API service experiences an outage +* your API key is about to expire +* your API usage becomes excessive or abnormal +* a voluntary survey of our users, but no more than once every 6 months + +We store the mapping from tokens to email addresses in a location separate from +server logs, using security measures consistent with our internal information +security practices to help us keep your information secure. We only retrieve +this mapping to resolve cases of excessive or abnormal usage. We automatically +disassociate an email address from its API key when the API key has not been +used for six months, or upon user request. You can request that your +email address be removed from our records by filling out a +[deletion request](https://forms.gle/GucFmZHTMgEFjH197). + +For more information, see +[Carnegie Mellon’s privacy notice](https://www.cmu.edu/legal/privacy-notice.html). +Further questions can be directed to delphi-support+privacy@andrew.cmu.edu. \ No newline at end of file diff --git a/docs/epidata_development.md b/docs/epidata_development.md index a2f0b7e8e..29a0fdde7 100644 --- a/docs/epidata_development.md +++ b/docs/epidata_development.md @@ -1,6 +1,6 @@ --- title: Epidata API Development Guide -nav_order: 3 +nav_order: 4 --- # Epidata API Development Guide diff --git a/docs/index.md b/docs/index.md index c49e97467..8dacc6906 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,6 +14,25 @@ group](https://delphi.cmu.edu/). The Epidata API includes: quick access to COVID data are available. - [Data about other diseases](api/README.md), including influenza, dengue, and other diseases tracked by Delphi through various data streams. + +Anyone may access the Epidata API anonymously without providing any personal +data. Anonymous API access is currently rate-limited and restricted to public +datasets with a maximum of two of the requested parameters having multiple +selections (signals, dates, versions, regions, etc). + +To request access to restricted datasets, no rate limit, and unlimited multiple +selections, you can [request a registered API key](https://forms.gle/hkBr5SfQgxguAfEt7). + +If you regularly or frequently use our system, please consider using an API key +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. + +For more information about how we use the data you provide us through your +registration and API request activity, see our +[Privacy Statement](api/privacy_statement.md). At any time, you may submit a +[Deletion Request](https://forms.gle/GucFmZHTMgEFjH197) to have us deactivate your key and destroy all +information associating that key with your identity. The Delphi group is extremely grateful to Pedrito Maynard-Zhang for all his help with the Epidata API [documentation](api/README.md). diff --git a/docs/new_endpoint_tutorial.md b/docs/new_endpoint_tutorial.md index 436b89908..d4deed6d4 100644 --- a/docs/new_endpoint_tutorial.md +++ b/docs/new_endpoint_tutorial.md @@ -1,6 +1,6 @@ --- title: New Endpoint Tutorial -nav_order: 4 +nav_order: 5 --- # Tutorial: Adding a new API endpoint diff --git a/docs/symptom-survey/index.md b/docs/symptom-survey/index.md index ac1ba9ac7..ec926dea3 100644 --- a/docs/symptom-survey/index.md +++ b/docs/symptom-survey/index.md @@ -1,7 +1,7 @@ --- title: COVID-19 Trends and Impact Survey has_children: true -nav_order: 5 +nav_order: 6 --- # COVID-19 Trends and Impact Survey