|
| 1 | +--- |
| 2 | +title: API Keys |
| 3 | +nav_order: 1 |
| 4 | +has_children: true |
| 5 | +--- |
| 6 | + |
| 7 | +# Epidata API Keys |
| 8 | + |
| 9 | +Anyone may access the Epidata API anonymously without providing any personal |
| 10 | +data. Anonymous API access is subject to the following restrictions; they may |
| 11 | +change as we learn more about their impact: |
| 12 | + |
| 13 | +1. public datasets only |
| 14 | +1. rate-limited to 60 requests per hour |
| 15 | +1. only two parameters may have multiple selections |
| 16 | + |
| 17 | +For example, a query for three signals on one date across all counties can be |
| 18 | +submitted anonymously, but a query for three signals on a period of four weeks |
| 19 | +across all counties requires an API key. |
| 20 | + |
| 21 | +An API key is a pseudonymous access token that grants privileged access to the |
| 22 | +Epidata API. You can request an API key by |
| 23 | +[registering with us](https://forms.gle/hkBr5SfQgxguAfEt7). |
| 24 | +Privileges of registration may include: |
| 25 | + |
| 26 | +1. no rate limit |
| 27 | +1. no limit on multiple selections |
| 28 | + |
| 29 | +We require an email address for all registrations so that we can contact you to |
| 30 | +resolve problems with excessive or abnormal usage patterns. Any additional |
| 31 | +personal information you provide to us at registration will be much appreciated, |
| 32 | +because it will help us understand what our data is used for and inform our |
| 33 | +plans and priorities, but is voluntary. For more information on how we use and |
| 34 | +store the information you provide us at registration time, see our |
| 35 | +[privacy statement](api/privacy_statement.md). |
| 36 | + |
| 37 | +## Usage |
| 38 | + |
| 39 | +If you choose to [register for an API key](https://forms.gle/hkBr5SfQgxguAfEt7), |
| 40 | +there are several ways to use your key to authenticate your requests: |
| 41 | + |
| 42 | +### Via request parameter |
| 43 | + |
| 44 | +The request parameter “api_key” can be used to pass the API key to the server. |
| 45 | +Example: |
| 46 | + |
| 47 | + https://api.delphi.cmu.edu/epidata/covidcast/meta?api_key=your_api_key_here |
| 48 | + |
| 49 | +### Via Basic Authentication |
| 50 | + |
| 51 | +Another method is using the HTTP basic authorization header with the username |
| 52 | +"epidata" and the API key as the password. Example: |
| 53 | + |
| 54 | +``` |
| 55 | +curl -u 'epidata:your_api_key_here' https://api.delphi.cmu.edu/epidata/covidcast/meta |
| 56 | +``` |
| 57 | + |
| 58 | +### Via Bearer Token |
| 59 | + |
| 60 | +Another method is providing the key in a bearer token header. Example: |
| 61 | + |
| 62 | +``` |
| 63 | +curl -H 'Authorization: Bearer your_api_key_here' https://api.delphi.cmu.edu/epidata/covidcast/meta |
| 64 | +``` |
0 commit comments