Skip to content
Docs navigation

Agents as developers

Alerts

Smarter Weather covers the 50 US states and DC only. Every route that takes a point (lat and lon, zip or location) returns 404 outside-coverage for a point outside the 50 states and DC. /v1/alerts and /v1/observations return it for a bounding box that touches no US domain (CONUS, Alaska, Hawaii); a box that touches one may still include area outside the US. /v1/weather/batch reports it per item as outside_coverage, and /v1/point with points and /v1/series/batch mark such points out_of_domain, as they do a point the check could not reach in time (retry it). If the location lookup is unavailable, the check can briefly fail open. Routes keyed by a station, radar site, forecast office or alert id, and nationwide lists, are not filtered by point, so do not treat an empty result as an all-clear. See Errors.

Search active NWS weather alerts by point or bounding box, look up a single alert by id, or post a polygon to compute who is in the path. Active alerts for a point also arrive inside the unified weather response.

How alerts are exposed

  • Embedded in the weather response. When you request weather for a location, any active alerts affecting that location come back in the same payload.
  • Search by point or bounding box (GET /v1/alerts). Pass lat and lon for the alerts in effect at a point, or min_lon, min_lat, max_lon, max_lat for the alerts that intersect a box.
  • Individually by alert ID. Use the per-alert lookup for the full payload — description, instruction, and polygon geometry — for detail views and notification deep links.
  • Population exposure. Post a polygon when an alerting or operations tool needs a count of people inside the hazard, not just the geometry.

Alert content

Each alert carries NWS metadata (sender, event type, onset and expiration), human-readable text, affected counties, and a polygon for map rendering.

Alert severity levels

Smarter Weather mirrors the NWS severity taxonomy without re-classifying. Use these to drive icon color and notification priority.

SeverityDescription
ExtremeExtraordinary threat to life or property
SevereSignificant threat to life or property
ModeratePossible threat to life or property
MinorMinimal threat to life or property
# first: export SMARTERWEATHER_API_KEY=sw_live_... (or: set -a; source .env; set +a)
curl "https://api.smarterweather.com/v1/alerts?lat=41.88&lon=-87.63" \
  -H "Authorization: Bearer $SMARTERWEATHER_API_KEY"
// save as sample.mjs; run: node --env-file=.env sample.mjs (Node 20.6+, ESM top-level await)
const res = await fetch(
  "https://api.smarterweather.com/v1/alerts?lat=41.88&lon=-87.63",
  { headers: { Authorization: `Bearer ${process.env.SMARTERWEATHER_API_KEY}` } },
);
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
console.log(JSON.stringify(data, null, 2));
import os, sys, requests

r = requests.get(
    "https://api.smarterweather.com/v1/alerts",
    params={"lat":"41.88","lon":"-87.63"},
    headers={"Authorization": f"Bearer {os.environ['SMARTERWEATHER_API_KEY']}"},
)
if not r.ok:
    sys.exit(f"{r.status_code} {r.text}")
data = r.json()
print(data)
package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.smarterweather.com/v1/alerts?lat=41.88&lon=-87.63", nil)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SMARTERWEATHER_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)
	if err != nil {
		log.Fatal(err)
	}
	if res.StatusCode < 200 || res.StatusCode > 299 {
		log.Fatalf("%s %s", res.Status, body)
	}
	fmt.Println(string(body))
}

Alerts reference

Rendered live from the canonical OpenAPI document. This is the canonical reference for the alerts resource.

Paste a test key (sw_test_*) from your dashboard into Test Request. Calls with your own key count toward your plan.

Loading API reference…