The endpoints on the REST page stay public, with no key, for this site and anyone who reads them politely. An API key is for software you run yourself: a script, a dashboard, your own app. Every request it makes is counted against your account and limited per key rather than per address, so a NAT or a shared office does not cost you anything.
Keyed access is under the API Terms of Use and Terms §20, as well as everything the public endpoints are under.
Make a key
Sign in, open Account, and use Create a key. Pick what it can read and when it expires. Keys expire after 30 days unless you choose a longer term or Never. The key is shown once. Copy it then; it is stored only as a hash and nobody can show it to you again. A lost key is revoked and replaced.
Keys look like wx_live_ followed by 43 characters. You can hold up to ten
live keys. Use one per program, so revoking one stops only that program.
Send it
Use the same paths as the public API, with /v1 in front, and send the key in
a header. Both of these work. Use whichever your client can set.
curl -H "X-API-Key: wx_live_..." https://api.wxalerts.org/v1/alerts/active
curl -H "Authorization: Bearer wx_live_..." https://api.wxalerts.org/v1/alerts/activeNever put a key in a URL. A request with ?key= or ?api_key= on /v1 is
refused with 400 key_in_query, because URLs end up in logs, browser history
and Referer headers. If you sent one that way, revoke it and make a new one.
Never put a key in a web page. Anyone who opens the page can read it. A page in the browser should use the public endpoints, which need no key.
Scopes
A key reads only what its scopes allow. New keys get every scope below except
placefile:read unless you choose otherwise.
| Scope | Paths under /v1 |
|---|---|
alerts:read |
/alerts/*, /stats/* |
weather:read |
/forecast, /forecast/sounding, /conditions, /stations/*, /weather, /sky/outlook |
outlooks:read |
/outlooks/*, /tropical/*, /winter/* |
storms:read |
/storms/*, /lightning/* |
reports:read |
/lsr/reports |
locations:read |
/locations/* |
placefile:read |
The full spotter report placefile. Meteorologist accounts only. |
placefile:read is the one exception to the header rule: GR software cannot
send a header, so that key goes in the placefile URL as ?key=. Keep that URL
private.
Limits
Each key may make about 300 requests a minute, with short bursts allowed.
The endpoints that return large geometry keep their own tighter limits, charged
to the key. Every /v1 response carries:
| Header | Meaning |
|---|---|
RateLimit-Limit |
The burst size for this key |
RateLimit-Remaining |
Requests left in the burst |
RateLimit-Reset |
On a 429, seconds until you may retry |
Retry-After |
On a 429, the same |
Responses keep their ETag, so send If-None-Match and take the 304. The
data changes on the order of minutes. Polling faster than that buys nothing.
For alerts as they happen, use MQTT instead of polling.
/v1 responses are Cache-Control: private: your own client may cache them,
and no shared cache will.
Errors
| Status | detail.code |
What to do |
|---|---|---|
| 400 | key_in_query |
Move the key to a header, then revoke it |
| 401 | api_key_required |
Send a key |
| 401 | api_key_invalid |
The key is unknown, revoked or expired |
| 403 | insufficient_scope |
Add the scope on the Account page, or use another key |
| 429 | rate_limited |
Wait Retry-After seconds |
Revoking
Revoke a key from the Account page. It stops working within a minute everywhere. A key also stops working if it expires or if the account is disabled or deleted.
The Account page shows when each key was last used and how many requests it made in the last 30 days. The counts trail by up to a minute.