How to make, send and revoke a key is in Make, send and revoke an API key.
Key format and lifetime
| Format | wx_live_ followed by 43 characters |
| Live keys per account | up to ten |
| Expiry | 30 days unless a longer term or Never is chosen when the key is made |
| Storage | only a hash is stored; the key is shown once |
Sending a key
| Form | Example |
|---|---|
X-API-Key header |
X-API-Key: wx_live_... |
Authorization header |
Authorization: Bearer wx_live_... |
Use the same paths as the public API, with /v1 in front. A key is never sent
in the URL. A request with ?key= or ?api_key= on /v1 is refused with
400 key_in_query.
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. Without a key the placefile is the public one, with restricted
reports filtered out. A key that is unknown, revoked or no longer held by a
meteorologist gets that same public file, not an error, so the layer in
your radar software keeps drawing.
What needs a key
The public routes work without one, limited per address. A key on those same
paths (with or without /v1) is charged to the key instead. The endpoints the
site does not use are served only under /v1 and always need one (the
route index has both lists): /alerts/active, /alerts/active/geojson,
/stats/lightning/daily, /storms/active, /storms/{id},
/storms/couplets/{id}/cone, /forecast/sounding, /visibility,
/visibility/point, and everything under /tropical and /winter.
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, /forecast/raw (on keys enabled for it; see Raw model data), /conditions, /stations/*, /weather, /sky/outlook, /visibility/* |
outlooks:read |
/outlooks/*, /tropical/*, /winter/* |
storms:read |
/storms/*, /lightning/* |
reports:read |
/lsr/reports |
placefile:read |
The full spotter report placefile. Meteorologist accounts only. |
Per-key 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.
The limits for clients without a key are on Rate limits.
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 |
The full list of status codes is on Errors.