Using API Keys with USGS water data APIs

These APIs use API keys managed by api.data.gov. Providing your own key means you can make more requests per hour before getting rate limited -- that is, before getting 429 "Too Many Requests" error responses. You can generate a key from our signup page; the key will be sent to the email address you provide.

To use your API key, you can pass it to the api_key query parameter:

https://api.waterdata.usgs.gov/ogcapi/v0/daily/items?limit=1&api_key=DEMO_KEY

Replace "DEMO_KEY" in that example with your own API key.

If you prefer (or if you're making POST requests), you can instead pass your API Key using the X-Api-Key header. For instance, using curl's -H flag to add the header:

curl -X POST -H 'X-Api-Key: DEMO_KEY' 'https://api.waterdata.usgs.gov/ogcapi/v0/daily/items?limit=1'

Either of these approaches will attach your API key to your requests and give you access to higher rate limits.

Information on the rate limits for a given endpoint, and how many requests you can make before being rate limited, are provided in the X-RateLimit-Limit and X-RateLimit-Remaining headers attached to the responses from each endpoint:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998