API Documentation

REST + JSON. One base URL, two endpoints. Data refreshes daily from four federal feeds: NWS alerts, FEMA declarations, USGS earthquakes, and IPAWS emergency alerts.

Authentication

Pass your API key in the x-api-key header (or as a bearer token in Authorization). Get a key by signing up free; manage and rotate it in your account.

curl -H "x-api-key: zpa_..." "https://zipawa.com/api/v1/events?zips=90210"

GET /api/v1/events

The primary endpoint: returns the full event context for each ZIP you pass — every active event with its timing (forecast / active / aftermath), category, severity, and time window. You filter; you decide what to act on.

Parameter	Required	Description
`zips`	yes	Comma-separated 5-digit ZIP codes, 1–1,000 per request.
`timing`	no	Comma-separated: `forecast`(hasn't happened — watches, approaching storms), `active` (happening now), `aftermath` (occurred; community recovering). Default: all.
`category`	no	Comma-separated: `wildfire`, `hurricane`, `tornado`, `severe_weather`, `flood`, `winter`, `earthquake`, `public_health`, `infrastructure`, `transportation`, `civil_unrest`, `mass_violence`, `custom`.
`min_severity`	no	`low` \| `moderate` \| `high` \| `critical`. Default: `low` (everything).
`at`	no	ISO 8601 timestamp for point-in-time/audit queries. Default: now.

Example

curl -H "x-api-key: zpa_..." \
  "https://zipawa.com/api/v1/events?zips=93534,33401&timing=aftermath&min_severity=high"

{
  "as_of": "2026-06-11T14:02:11.000Z",
  "filters": { "timing": ["aftermath"], "min_severity": "high", "category": "all" },
  "zips": [
    {
      "zip": "93534",
      "events": [
        {
          "event_id": "evt_8x2kq01ab3",
          "category": "wildfire",
          "severity": "critical",
          "timing": "aftermath",
          "title": "FEMA DR-4920: WILDFIRES (CA)",
          "source": "fema",
          "source_event_type": "Fire",
          "window": {
            "starts_at": "2026-06-07T03:15:00.000Z",
            "expires_at": "2026-07-22T00:00:00.000Z",
            "phase": "decay"
          }
        }
      ]
    },
    { "zip": "33401", "events": [] }
  ]
}

Every requested ZIP appears in zips; an empty events array means no matching context. window.phase is upcoming, peak, or decay relative to the query time.

GET /api/v1/suppressions

The opinionated shortcut for "where should I not market right now?" Applies our recommended filter — excludes forward-looking forecasts and low-severity nuisance context — and splits your list into suppress and clear.

Parameter	Required	Description
`zips`	yes	Comma-separated 5-digit ZIP codes, 1–1,000 per request.
`category`	no	Single category filter.
`at`	no	ISO 8601 timestamp for point-in-time/audit queries.

curl -H "x-api-key: zpa_..." "https://zipawa.com/api/v1/suppressions?zips=93534,90210"

{
  "as_of": "2026-06-11T14:02:11.000Z",
  "suppress": [
    {
      "zip": "93534",
      "event_id": "evt_8x2kq01ab3",
      "category": "wildfire",
      "severity": "critical",
      "timing": "aftermath",
      "reason": "FEMA DR-4920: WILDFIRES (CA)",
      "source": "fema",
      "window": { "starts_at": "...", "expires_at": "...", "phase": "decay" }
    }
  ],
  "clear": ["90210"]
}

Errors & limits

Status	Error	Meaning
`400`	`bad_request`	Missing or invalid parameter — the `detail` field explains.
`401`	`unauthorized`	Missing, invalid, or revoked API key.
`429`	`quota_exceeded`	Free tier allows 5,000 ZIP screenings per calendar month (each ZIP in a request counts as one screening). Track usage in your dashboard.

Data sources & freshness

Events are ingested automatically from the National Weather Service alerts API (live weather watches, warnings, and advisories), FEMA disaster declarations (federally declared disasters with recovery windows), USGS earthquakes (M4.5+ with magnitude-scaled impact radii), and FEMA IPAWS emergency alerts (local civil emergencies, law-enforcement warnings, hazmat, and 911 outages), refreshed daily. County-coded events fan out to ZIP codes via the US Census ZCTA crosswalk. Severity is normalized to four levels, and routine nuisance alerts are filtered before they ever reach the API.