back
loading skill details...
US weather forecasts via National Weather Service (NWS) with automatic fallback to global weather for non-US locations. Provides detailed accumulation data,...
---
name: weather-nws
description: "US weather forecasts via National Weather Service (NWS) with automatic fallback to global weather for non-US locations. Provides detailed accumulation data, watches/warnings, and actionable timing. Use for: US-based weather queries, winter storm forecasts, precipitation accumulation estimates, severe weather alerts. Automatically falls back to global weather via wttr.in for international locations."
homepage: https://api.weather.gov/
metadata: {"clawdhub":{"emoji":"๐ฆ๏ธ"},"clawdis":{"envVars":[{"name":"AIRNOW_API_KEY","required":false,"description":"AirNow API Key for AQI lookup"}]}}
---
# Weather NWS Skill
Get detailed US weather forecasts from the National Weather Service with automatic global fallback, hourly forecasts, air quality data, and structured winter storm accumulations.
## What This Skill Does
This skill operates in **8 modes** to match your query:
| Mode | When It Activates | What You Get |
|------|-------------------|--------------|
| ๐ฆ๏ธ **Standard Forecast** | Default (no time specified) | 12-hour forecast with today/tonight/tomorrow |
| โฐ **Hourly Forecast** | Time-specific query detected | Hour-by-hour breakdown (~156 periods, 7 days) |
| ๐จ๏ธ **Winter Storm** | Keywords like "snow," "storm" | 12-hour + structured accumulation data |
| ๐จ **AQI Report** | `--aqi` flag included | Current + forecast air quality index |
| ๐ก๏ธ **Observed vs Forecast** | `--current` flag included | Current station readings with comparison |
| โ๏ธ **Astronomical Times** | `--astro` flag included | Sunrise/sunset, twilight, moon phase |
| โ๏ธ **Aviation Forecast** | `--taf` flag included | Terminal Aerodrome Forecast (TAF) |
| ๐ฅ **Fire Weather** | `--fire` flag included | Fire danger, red flag warnings |
| ๐ **Global Fallback** | Non-US location | wttr.in data (less detailed) |
## AirNow API Key (Optional but Recommended)
The AirNow API **works without a key** but has limitations:
| Without API Key | With API Key |
|-----------------|--------------|
| Rate limited (requests may fail) | Higher rate limits |
| No guaranteed availability | Priority access |
| May return empty results | Reliable AQI data |
### Getting an API Key
1. Visit: https://docs.airnowapi.org/account/request/
2. Fill out the request form (free for personal use)
3. Key arrives via email within 1-2 business days
### Setting the API Key
**Option 1: Environment Variable (Recommended)**
```bash
export AIRNOW_API_KEY="your-api-key-here"
```
**Option 2: OpenClaw Config (Persistent)**
Add to your OpenClaw config under `skills.entries.weather-nws.env`:
```json
{
"skills": {
"entries": {
"weather-nws": {
"env": {
"AIRNOW_API_KEY": "your-api-key-here"
}
}
}
}
}
```
## When to Use
โ
**USE this skill when:**
- "What's the weather in [US city]?"
- "How much snow is expected?"
- "Winter storm forecast for [location]"
- "Will it rain tomorrow in [US city]?"
- "What time will the rain stop?"
- "Air quality in [city] today"
- Any US-based weather query
๐ **Automatic fallback:**
- Non-US locations โ wttr.in
- NWS API unavailable โ wttr.in
- Both sources fail โ clear error message
## Quick Start
```bash
# Run the unified weather script
python3 ./scripts/get_weather.py "New York, NY"
# Force specific source if needed (normally auto-detected)
python3 ./scripts/get_weather.py "London, UK" --source wttr
# Get hourly forecast (auto-detected or forced)
python3 ./scripts/get_weather.py "Boston at 8 PM"
python3 ./scripts/get_weather.py "Chicago" --hourly
# Include air quality
python3 ./scripts/get_weather.py "Seattle" --aqi
```
## Hourly Auto-Detection
The skill automatically detects time-specific language and switches to hourly forecast:
```
"Boston at 8 PM" โ โฐ Hourly mode
"Boston tonight" โ โฐ Hourly mode
"Boston tomorrow morning" โ โฐ Hourly mode
"Boston at 5:30" โ โฐ Hourly mode
"When will it stop raining?" โ โฐ Hourly mode
```
**Patterns detected:**
- `at 8 PM`, `at 5:30`, etc.
- `tonight`, `this afternoon`
- `tomorrow morning/afternoon/night`
- `when will...`, `how long until...`
## Air Quality (`--aqi`)
Adds AirNow AQI data to any forecast:
```bash
python3 ./scripts/get_weather.py "Boston" --aqi
```
**Output includes:**
- Current AQI with color-coded emoji (๐ข ๐ก ๐ ๐ด ๐ฃ ๐ต)
- Primary pollutant (PM2.5, O3, etc.)
- Health recommendation based on category
- 3-day AQI forecast
**AQI Categories:**
| Range | Category | Emoji | Recommendation |
|-------|----------|-------|------------------|
| 0-50 | Good | ๐ข | Enjoy outdoor activities |
| 51-100 | Moderate | ๐ก | Sensitive groups limit exertion |
| 101-150 | Unhealthy for Sensitive Groups | ๐ | Children/elderly limit outdoor activities |
| 151-200 | Unhealthy | ๐ด | Everyone reduce outdoor exertion |
| 201-300 | Very Unhealthy | ๐ฃ | Avoid outdoor activities |
| 301-500 | Hazardous | ๐ต | Stay indoors โ health alert |
## Output Format
The script provides consistent output regardless of source:
**Header:** Location and current alert status
**Today โ Tonight โ Tomorrow:** Structured timeline
**Accumulation:** Specific snow/rain amounts when available
**Bottom Line:** Actionable summary with timing
## Implementation
The script handles:
1. Geocoding location to lat/long
2. Detecting if location is in US
3. Calling NWS API for US locations (detailed accumulation)
4. Falling back to wttr.in for non-US (basic forecast)
5. Formatting consistent output with emojis and structure
## Limitations
- **NWS:** US only, requires internet, rate limited
- **wttr.in:** Global, less detail on accumulation, no official watches/warnings
- **AirNow:** US + Canada only, requires API key for reliable access
## Examples
**US winter storm query:**
```bash
python3 ./scripts/get_weather.py "Boston, MA"
```
โ Returns NWS data with accumulation estimates
**International location:**
```bash
python3 ./scripts/get_weather.py "Toronto, Canada"
```
โ Automatically uses wttr.in, notes it's non-US
**With air quality:**
```bash
python3 ./scripts/get_weather.py "Seattle" --aqi
```
โ Weather + AQI data with health recommendations
**Observed vs Forecast:**
```bash
python3 ./scripts/get_weather.py "Boston" --current
```
โ Current station readings with forecast comparison
**Combined features:**
```bash
python3 ./scripts/get_weather.py "Seattle" --aqi --current
```
โ Full weather report with all data sources
**Phase 3 features:**
```bash
python3 ./scripts/get_weather.py "Boston" --astro # Sunrise/sunset times
python3 ./scripts/get_weather.py "SFO" --taf # Aviation forecast
python3 ./scripts/get_weather.py "California" --fire # Fire weather
python3 ./scripts/get_weather.py "Denver" --astro --aqi --current # Everything!
```
## Observed vs Forecast (`--current`)
Shows actual measured conditions from the nearest NWS observation station alongside the forecast:
```
๐ก๏ธ **Observed Conditions**
**Actually 43ยฐF (3ยฐ warmer than 40ยฐ forecast)**
โ๏ธ Partly Cloudy
๐จ WNW 8 mph โข ๐ง 36% humidity โข ๐ซ๏ธ Dewpoint 18ยฐF โข ๐ Pressure 29.86 inHg โข ๐ Visibility 10+ mi
```
**Fields shown:**
- Temperature with forecast delta
- Conditions description
- Wind speed and direction
- Humidity percentage
- Dewpoint
- Barometric pressure (inHg)
- Visibility
## Alert Priorities
When alerts are active, they're displayed with enhanced formatting using severity/urgency/certainty weighting:
| Factor | Weights |
|--------|---------|
| **Severity** | Extreme (4) > Severe (3) > Moderate (2) > Minor (1) |
| **Urgency** | Immediate (3) > Expected (2) > Future (1) |
| **Certainty** | Observed (3) > Likely (2) > Possible (1) |
**Severity Styling:**
| Severity | Emoji | Badge |
|----------|-------|-------|
| Extreme | โซ | EXTREME |
| Severe | ๐ด | SEVERE |
| Moderate | ๐ | MODERATE |
| Minor | ๐ก | MINOR |
**Alert display includes:**
- Event name with severity badge
- Urgency tag: โฐ Immediate / ๐
Expected / ๐ฎ Future
- Time range (onset โ expires)
- First sentence of description
- Recommended response action
**Example:**
```
๐ [**MODERATE**] **Winter Storm Warning**
๐
Expected | *Winter Storm Warning from 6 PM to 10 AM EST*
๐ 6:00 PM โ 10:00 AM
๐ Heavy snow expected with accumulations of 6-10 inches...
๐ ๐ Prepare now
```
## References
- [references/nws-api.md](references/nws-api.md) โ NWS API endpoint details
- [references/airnow-api.md](references/airnow-api.md) โ AirNow API documentation
## Phase 3 Features
### Astronomical Times (`--astro`)
Shows sunrise, sunset, civil twilight, and moon phase information:
```bash
python3 ./scripts/get_weather.py "Boston" --astro
```
**Output includes:**
- ๐
**Sunrise:** Time with countdown/ago
- ๐ **Sunset:** Time with countdown/ago
- ๐ก **Civil Twilight:** Dawn and dusk times (useful for runners, cyclists)
- โฑ๏ธ **Daylight:** Total hours of daylight
- ๐ **Moon:** Current phase with illumination percentage
**Example:**
```
โ๏ธ **Astronomical Times โ Boston**
๐
**Sunrise:** 6:22 AM (12h ago)
๐ **Sunset:** 5:31 PM (in 2h)
๐ก **Civil Twilight:** 5:55 AM โ 5:58 PM
โฑ๏ธ **Daylight:** 11h 9m
๐ **Moon:** ๐ First Quarter (50.0%)
```
### Aviation Forecast (`--taf`)
Shows Terminal Aerodrome Forecast (TAF) for the nearest aviation weather station:
```bash
python3 ./scripts/get_weather.py "SFO" --taf
```
**Note:** TAFs are designed for aviation use. The report provides:
- Station identifier
- Wind conditions and direction
- Visibility
- Cloud ceiling information
**Important:** *This is informational only. Always check official sources for flight planning.*
### Fire Weather (`--fire`)
Shows fire danger information for wildfire-prone areas:
```bash
python3 ./scripts/get_weather.py "California" --fire
```
**Output includes:**
- Fire danger level (if elevated)
- ๐ฅ **Red Flag Warnings** (if active)
- Fire weather zone forecast
- Source attribution
**Red Flag Warnings** indicate critical fire weather conditions (low humidity + high winds).
## Changelog
### v1.3.0 (2026-02-26) - Phase 3
- Added `--astro` flag for sunrise/sunset, twilight, and moon phase
- Added `--taf` flag for Aviation Terminal Aerodrome Forecasts
- Added `--fire` flag for fire weather danger and red flag warnings
- Added moon phase calculation (waxing/waning, illumination %)
- Added daylight hours calculation
- Added civil twilight detection for runners/cyclists
### v1.2.0 (2026-02-26) - Phase 2
- Added `--current` flag for station observations vs forecast comparison
- Enhanced alert formatting with severity/urgency/certainty priority scoring
- Added temperature delta comparison (warmer/cooler than forecast)
- Added full observation details: humidity, dewpoint, pressure, visibility
### v1.1.0 (2026-02-26)
- Added hourly forecast with temporal query auto-detection
- Added AirNow AQI integration (`--aqi` flag)
- Added structured grid data for winter storm accumulations
- Fixed AirNow API endpoint URLs
### v1.0.0 (2026-02-22)
- Initial release: NWS API with wttr.in fallback
- 12-hour forecast periods
- Alert integration
- Accumulation estimates from text parsing
don't have the plugin yet? install it then click "run inline in claude" again.