weather-alerts/README.md

Weather Alerts

A Python application that monitors weather forecasts and sends push notifications when conditions match your alert rules.

How It Works

1. Queries the Visual Crossing Weather API for upcoming forecast data
2. Evaluates forecast conditions against configurable alert rules
3. Sends notifications to an ntfy server when alert conditions are triggered
4. Tracks sent alerts to prevent duplicate notifications

Configuration

All configuration is managed in app/config/settings.yaml. Copy from settings.example.yaml to get started:

cp app/config/settings.example.yaml app/config/settings.yaml

Location Configuration

Set your location in settings.yaml under the weather.location field.

Supported Location Formats

Visual Crossing supports several location formats:

Format	Example	Notes
City, State (US)	"Chicago,IL"	State abbreviation or full name
City, Country	"Paris,France", "Tokyo,Japan"	For international locations
City, State, Country	"Chicago,IL,USA"	Most explicit format
Full Address	"620 Herndon Parkway, Herndon, Virginia, 20170, USA"	Street-level precision
ZIP/Postal Code	"20170"	US ZIP codes work directly
Coordinates	"40.7128,-74.0060"	Latitude,longitude in decimal degrees

Location Best Practices

• Include state/country to avoid ambiguity (many cities share names like "Springfield")
• Coordinates are fastest and most precise - no geocoding lookup required
• URL encoding is handled automatically by the application

Coordinate Format

For latitude/longitude coordinates:

• Latitude: -90 to 90 (negative values = southern hemisphere)
• Longitude: -180 to 180 (negative values = western hemisphere)
• Format: "latitude,longitude" (e.g., "35.8456,-86.4244" for Viola, TN)

Alert Rules Configuration

Configure alert rules under alerts.rules in settings.yaml. Each rule can be independently enabled or disabled.

Temperature Alerts

temperature:
  enabled: true
  below: 32    # Alert when temperature falls below (freezing warning)
  above: 95    # Alert when temperature exceeds (heat warning)

Both thresholds are optional - set only the ones you need.

Precipitation Alerts

precipitation:
  enabled: true
  probability_above: 60  # Alert when rain/snow chance exceeds this percentage

Wind Alerts

wind:
  enabled: true
  speed_above: 25   # Sustained wind threshold (mph for "us" units)
  gust_above: 30    # Wind gust threshold (mph for "us" units)

Either threshold can trigger an alert independently.

Severe Weather Alerts

severe_weather:
  enabled: true  # Forward NWS severe weather alerts from the API

When enabled, forwards official severe weather alerts (tornado warnings, flash flood warnings, etc.) from the National Weather Service via the Visual Crossing API.

Other Configuration Options

Weather Settings

weather:
  location: "viola,tn"    # Your location (see formats above)
  hours_ahead: 24         # How many hours of forecast to check
  unit_group: "us"        # "us" for Fahrenheit/mph, "metric" for Celsius/kph

Notification Settings

notifications:
  ntfy:
    server_url: "https://ntfy.sneakygeek.net"
    topic: "weather-alerts"
    priority: "high"              # min, low, default, high, urgent
    tags: ["cloud", "warning"]    # Emoji tags for notifications

State Management

state:
  file_path: "./data/state.json"
  dedup_window_hours: 24  # Prevent duplicate alerts within this time window

The deduplication window prevents the same alert from being sent repeatedly. A "High Wind Warning" at 3 PM won't be sent again until 24 hours later (with default settings).

Application Settings

app:
  name: "weather-alerts"
  version: "1.0.0"
  log_level: "INFO"  # DEBUG, INFO, WARNING, ERROR

Environment Variables

Create a .env file in the project root with your secrets:

VISUALCROSSING_API_KEY=your_api_key_here
NTFY_ACCESS_TOKEN=your_ntfy_token_here

Variable	Required	Description
VISUALCROSSING_API_KEY	Yes	API key from Visual Crossing
NTFY_ACCESS_TOKEN	Yes*	Authentication token for ntfy server (*if server requires auth)

Example Configuration

Here's a complete example for monitoring weather in New York City:

weather:
  location: "New York,NY,USA"
  hours_ahead: 12
  unit_group: "us"

alerts:
  rules:
    temperature:
      enabled: true
      below: 20     # Alert for very cold temps
      above: 95     # Alert for heat waves
    precipitation:
      enabled: true
      probability_above: 70
    wind:
      enabled: true
      speed_above: 30
      gust_above: 45
    severe_weather:
      enabled: true