# 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:

```bash
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

```yaml
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

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

### Wind Alerts

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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:

```bash
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](https://www.visualcrossing.com/) |
| `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:

```yaml
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
```