# US Weather Alerts API — NWS Warnings by State, Zone or Point (`keyman98/us-weather-alerts-api`) Actor

Get active US weather alerts (tornado, flood, hurricane, heat, winter storm...) from the official National Weather Service API. Search by state, NWS zone or lat/lon point, filter by severity and event type. Pay only for alerts returned.

- **URL**: https://apify.com/keyman98/us-weather-alerts-api.md
- **Developed by:** [KeyMan98](https://apify.com/keyman98) (community)
- **Categories:** News, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 alert returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## US Weather Alerts API — NWS Warnings by State, Zone or Point

Get every currently active severe weather alert — tornado warnings, flood watches, winter storm warnings, heat advisories, and every other National Weather Service alert type — for a US state, a specific NWS forecast zone, or an exact latitude/longitude point. Pulls data through the NWS's own official, public API (**api.weather.gov**) — no scraping, no third-party weather provider — and exports the results to CSV, Excel, or JSON.

### What you get (output fields)

For each active alert, one dataset row with:

- `id` — NWS alert identifier, unique per alert.
- `event` — alert type, e.g. `Tornado Warning`, `Flood Watch`, `Winter Storm Warning`.
- `severity` / `urgency` / `certainty` — NWS's own classification (e.g. severity: `Extreme`, `Severe`, `Moderate`, `Minor`, `Unknown`).
- `headline` — short one-line summary, as issued.
- `description` — full alert text (on by default; turn off `includeDescription` to skip it).
- `instruction` — recommended action for the public, when NWS provides one.
- `areaDesc` — human-readable description of the affected area(s).
- `affectedZones` / `states` — NWS zone codes covered by the alert, and the US state codes derived from them.
- `onset` / `effective` / `expires` / `ends` — the alert's timing.
- `senderName` — issuing NWS office.
- `status` / `messageType` — e.g. `Actual` / `Update`.
- `web` — the alert's own NWS API URL.
- `queryType` / `queryValue` — which input (state, zone, or point) found this alert.
- `error` — set only on rows that could not be resolved (see below); null otherwise.

### Who it's for

- **Logistics and delivery** — check active alerts along a route or in a service area before dispatching.
- **Insurance** — flag active severe-weather exposure by state or ZIP-level point.
- **Outdoor events** — check conditions for a venue's exact coordinates before an event.
- **Apps and dashboards** — feed structured, machine-readable alert data into a map or feed.
- **Automations and monitoring** — run on a schedule and trigger a notification when a new alert appears (see FAQ).

### How to use

1. **States** — one or more US state/territory 2-letter codes, e.g. `TX`, `FL`, `CA`.
2. **Zones (optional)** — NWS forecast/county zone codes, e.g. `TXZ211`, for one specific area instead of a whole state.
3. **Points (optional)** — `latitude,longitude` pairs, e.g. `32.7767,-96.7970`, for one exact location.
4. **Severities / event types (optional)** — narrow the results, e.g. only `Severe` and `Extreme`, or only `Tornado Warning`.
5. **Run the Actor.** Each active alert becomes one row. An alert covering more than one of your states/zones/points is only returned once.

### Input example (JSON)

```json
{
  "states": ["TX", "FL", "CA"],
  "zones": [],
  "points": [],
  "severities": [],
  "events": [],
  "includeDescription": true
}
```

### Output example (JSON)

```json
{
  "id": "urn:oid:2.49.0.1.840.0.e8b6eb8e3ea0784c510b3f1e1f21c671cc761aac.001.1",
  "event": "Flood Watch",
  "severity": "Severe",
  "urgency": "Future",
  "certainty": "Possible",
  "headline": "Flood Watch issued September 24 at 2:17AM MDT until September 25 at 6:00AM MDT",
  "areaDesc": "Guadalupe Mountains of Eddy County; Eastern Culberson County; Davis Mountains",
  "affectedZones": ["TXZ062", "TXZ066"],
  "states": ["TX"],
  "onset": "2026-09-24T02:17:00-06:00",
  "expires": "2026-09-24T14:15:00-06:00",
  "senderName": "NWS Midland/Odessa TX",
  "status": "Actual",
  "messageType": "Update",
  "web": "https://api.weather.gov/alerts/urn:oid:2.49.0.1.840.0.e8b6eb8e3ea0784c510b3f1e1f21c671cc761aac.001.1",
  "queryType": "state",
  "queryValue": "TX",
  "error": null
}
```

### If a state, zone or point is invalid

That entry becomes one **error row**: `error` is set to NWS's own explanation (e.g. an unknown state code, a malformed zone, or a point outside NWS's coverage), every other field is null except `queryType`/`queryValue`. The run does not fail, the rest of your inputs keep running, and **you are not charged** for that row.

If your whole run finds no active alerts and no errors, one extra **summary row** (`queryType: "summary"`, a `message` field, `error: null`) explains that — so the dataset is never silently empty.

### Pricing

Pay only for alerts actually returned — nothing charged for an invalid state/zone/point, for a query with no active alerts, or for the summary row. An alert found through more than one state/zone/point is only charged once. Pricing model: **pay-per-event**.

| Event | When it's charged | Price |
| --- | --- | --- |
| `alert-returned` | an active alert was returned in the results | 0.001 USD |

### Limitations

- Covers the US and its territories only (all areas NWS itself covers) — not other countries.
- **Active alerts only** — this is not a forecast. It does not predict future weather or return alerts that already expired.
- No historical alerts: only what's active right now, at the moment the Actor runs.
- A state, zone, and point cannot be mixed in the *same* underlying NWS request — this Actor already handles that by querying each one separately, so you can freely combine all three in one run.
- `states` is not validated locally against a hardcoded list — NWS is the source of truth; an unrecognized code comes back as a clear error row instead.

### FAQ

#### Am I charged if a state, zone or point is invalid?

No. You are only charged for alerts actually returned in the results.

#### What's the difference between states, zones and points?

A **state** returns every alert affecting that state. A **zone** is a smaller NWS forecast area (e.g. one county or part of one) — use it to narrow results to a specific spot. A **point** is one exact latitude/longitude — use it for one address or venue.

#### How do I find a zone code?

NWS publishes the full zone list at `weather.gov/gis/publicgis` and via `api.weather.gov/zones`; zone codes look like `TXZ211` (2-letter state + `Z`/`C` + 3 digits). If you don't already know the code, use a point (latitude/longitude) or the whole state instead.

#### Is this official National Weather Service data?

Yes. Every request goes straight to `api.weather.gov`, NWS's own public API, with no intermediate provider. Alert data is US government public-domain data.

#### How often is this updated?

Every time you run it — the results reflect whatever is active on api.weather.gov at that moment. NWS issues, updates, and cancels alerts continuously; there is no fixed refresh schedule to match, run the Actor whenever you need the current state.

#### Can I get notified when a new alert appears?

Yes. Run this Actor on a schedule (Apify's built-in scheduler) and compare the `id` field against your last run's results — a new `id` means a new alert.

#### Can I filter by severity or event type at the same time as by state?

Yes. `severities` and `events` apply to every state/zone/point in the same run.

#### Can I use this through the Apify API or an MCP server?

Yes, like any Apify Actor — through the standard Apify API, or through the Apify MCP server if you use Claude, Cursor, or another MCP-enabled client.

### Export

Results can be downloaded from the Apify dataset as JSON, CSV, or Excel, or accessed via the Apify API.

# Actor input Schema

## `states` (type: `array`):

US state/territory 2-letter codes (e.g. "TX", "FL", "CA"). Looked up against the National Weather Service's own area list.

## `zones` (type: `array`):

NWS forecast/county zone codes (e.g. "TXZ211"). Use this for one specific area instead of a whole state. See FAQ in the README for how to find a zone code.

## `points` (type: `array`):

Latitude,longitude pairs (e.g. "32.7767,-96.7970" for Dallas, TX). Use this for one exact location instead of a whole state.

## `severities` (type: `array`):

Only keep alerts of these severities: Extreme, Severe, Moderate, Minor, Unknown. Leave empty to keep every severity.

## `events` (type: `array`):

Only keep alerts of these event types, exactly as NWS names them (e.g. "Tornado Warning", "Flood Watch"). Leave empty to keep every event type.

## `includeDescription` (type: `boolean`):

Include the alert's full description text (can be long). Turn off to get only the headline and the other short fields.

## Actor input object example

```json
{
  "states": [
    "TX",
    "FL",
    "CA"
  ],
  "zones": [],
  "points": [],
  "severities": [],
  "events": [],
  "includeDescription": true
}
```

# Actor output Schema

## `results` (type: `string`):

All results in the default dataset (JSON, CSV, Excel).

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "states": [
        "TX",
        "FL",
        "CA"
    ],
    "zones": [],
    "points": [],
    "severities": [],
    "events": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("keyman98/us-weather-alerts-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "states": [
        "TX",
        "FL",
        "CA",
    ],
    "zones": [],
    "points": [],
    "severities": [],
    "events": [],
}

# Run the Actor and wait for it to finish
run = client.actor("keyman98/us-weather-alerts-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "states": [
    "TX",
    "FL",
    "CA"
  ],
  "zones": [],
  "points": [],
  "severities": [],
  "events": []
}' |
apify call keyman98/us-weather-alerts-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,keyman98/us-weather-alerts-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/zMbNwr37a3ds6KxG9/builds/5eaLOiPibR2oJwgJh/openapi.json