Community. Driven. Weather. Data. | Always Ad-Free | Developer FriendlyChecking statusDiscord
Become a supporter
Sign in
DocsDevelopersOverview

Build on WxAlerts

Poll the REST API or subscribe to the live MQTT feeds, with and without an API key.

Base URL: https://api.wxalerts.org

There are two ways to get weather data into your own software. The REST API is plain HTTPS and JSON that you poll: ask what is in effect at a point, in a box, or across the country. The MQTT feeds push NWS alerts and GOES lightning to you the moment they are published, so a client that listens needs no polling at all.

Most REST routes are public: no key needed, limited per address, and the same endpoints this site calls from the browser. The rest are served only under /v1 with an API key, which is also accepted on the public routes, with /v1 in front, to move the request off your address’s budget and onto the key’s. A key-only route on the bare path answers 401. Browsers block calls from other websites (CORS allows only wxalerts.org), so call the API from a server, script or app. The MQTT feeds are public and read only.

None of it is exempt from the Terms of Service; the clauses that decide what you may build are in Terms for builders.

Start here

TutorialMake your first API callAsk the REST API for the alerts in effect at a point, then for the current weather there, with no key.TutorialSubscribe to live alerts over MQTTConnect to the public broker from Python, subscribe to one county and print each NWS alert as it is published.

Guides

How-to guideMake, send and revoke an API keyCreate a key on your account page, send it in a header, and revoke it.How-to guideBuild a reliable MQTT clientWhat to handle in a client for the alerts and lightning feeds so it stays correct for months.How-to guideMerge lightning history with the live feedLoad recent flashes from the REST route, then carry on from MQTT without drawing any flash twice.How-to guidePoll the weather API politelyHow much of the weather response to ask for, and how often to ask, so a display stays fresh without wasted calls.

Concepts

ConceptRetained alerts, and tombstonesWhy the alerts feed keeps every live hazard on the broker, and how an empty message tells you one has ended.ConceptRank and color alerts by significanceWhy to color and sort alerts by VTEC significance rather than CAP severity, and how the API's own ranking orders them.ConceptStorm cell ids, freshness and conesWhy a storm keeps one id through merges and splits, what the feed age tells you, and how the wide and tight cone profiles were chosen.ConceptHow the sunrise and sunset scores workWhat goes into the colour score and the clear sun score for each sunrise and sunset, and why a cloudless evening rates Poor for colour.ConceptVisibility categories and where they come fromWhy the low visibility product sets no thresholds, and which four sources are fused into each area.ConceptThe winter weather productsWhat the Winter Storm Severity Index, the winter precipitation probabilities and the Day 3 to 7 hazards each measure.ConceptThe two forecast modelsWhy the forecast API keeps the National Blend of Models and the HRRR apart, and what its probabilities do and do not say.ConceptWhat is measured and what is forecastWhy the weather API's current block is measured while hourly and daily are forecast, and why the sky word and icon are decided on the server.

Reference

ReferenceAuthenticationThe key header forms, which routes need a key, the scopes, the per-key limits and the authentication error codes.ReferenceRate limitsThe request limits for clients without a key, the per-route limits and how to stay under them.ReferenceErrorsThe shape of an API error, what each status code means, and the errors specific to each resource.ReferenceTerms for buildersThe three clauses of the Terms of Service that decide whether what you are building is allowed.

MQTT

ReferenceMQTT alerts feedLive NWS hazards over MQTT-on-WebSocket, retained per hazard, tombstoned when they end, and filed by both issuing office and SAME code.ReferenceMQTT lightning feedLive GLM flashes over MQTT-on-WebSocket, with a geohash topic tree that doubles as the spatial index.

View this page as Markdown

May we use Microsoft Clarity to see how pages are used (clicks, scrolling and replays of a visit, with anything you type hidden), plus a random ID linking that to crash reports? Only to find bugs and confusing screens. Never advertising, never sold.

Alerts work the same either way. Change it any time under Privacy choices in the site footer.What we collect