weather-integration

name

weather-integration

description

Configure and troubleshoot weather-based irrigation skip rules using the Open-Meteo API. Use when asked to set up rain forecast skips, configure rain threshold values, debug why zones are or are not being skipped, check weather cache status, understand skip preview results, or tune skip rule sensitivity for your local climate. Triggers include "skip when rain", "weather threshold", "Open-Meteo", "skip preview", "rain forecast rule", "freeze protection", or any task involving weather-driven irrigation decisions.

weather-integration

Connect irrigation-scheduler to live weather data from Open-Meteo for automatic rain and freeze skip rules.

When to Use

• Setting up your first weather-based skip rule
• Tuning rain forecast thresholds for your local climate
• Diagnosing why a zone ran despite rain
• Diagnosing why a zone was skipped unexpectedly
• Understanding the weather cache and refresh cycle
• Previewing which zones will skip today before schedules fire

How It Works

irrigation-scheduler fetches hourly forecast data from the Open-Meteo API every 30 minutes. The raw response is stored in weather_cache in SQLite. When the cron scheduler evaluates a zone before each run, it reads the cached weather data and evaluates every active skip rule for that zone in order. If any rule matches, the run is recorded as skipped with the rule name and reason.

Manual runs bypass all skip rule evaluation.

Prerequisites

1. Latitude and longitude set in Settings (PUT /api/settings with latitude and longitude)
2. At least one skip rule attached to a zone
3. Server has outbound HTTPS access to api.open-meteo.com

Open-Meteo Fields Used

Field	Used For
precipitation_sum (daily)	rain_yesterday rule: yesterday total in mm
precipitation_probability_max + precipitation (hourly)	rain_forecast rule: sum over next H hours
temperature_2m_min (daily)	temperature_below rule: freeze protection

All values are in metric units (mm for precipitation, Celsius for temperature).

Skip Rule Reference

rain_forecast

Skips if the sum of forecast precipitation over the next N hours exceeds a threshold.

{
  "rule_type": "rain_forecast",
  "threshold_mm": 5.0,
  "window_hours": 24
}

Tuning guide:

• Dry climates: lower threshold (2-3mm) to skip on any meaningful rain
• Humid climates: higher threshold (8-12mm) to avoid over-skipping
• Drip irrigation: lower threshold since plants need less supplemental water
• Lawn irrigation: higher threshold since lawns need more volume

rain_yesterday

Skips if measured precipitation from the previous calendar day exceeded a threshold.

{
  "rule_type": "rain_yesterday",
  "threshold_mm": 10.0
}

Tuning guide:

• Sandy soil drains fast: lower threshold (6-8mm)
• Clay soil retains moisture: higher threshold (15-20mm)
• Raised beds: lower threshold (5-8mm)
• In-ground lawn: higher threshold (12-18mm)

temperature_below

Skips if the forecasted minimum temperature is below a threshold. Used for freeze protection.

{
  "rule_type": "temperature_below",
  "threshold_celsius": 2.0
}

Set to 2C (35F) for a safety margin above 0C (32F) to account for sensor variation.

API Quick Reference

# Check current weather cache
curl http://localhost:3001/api/weather

# Get skip preview for today (which zones will skip and why)
curl http://localhost:3001/api/weather/skip-preview

# Force a weather cache refresh
curl -X POST http://localhost:3001/api/weather/refresh

# List skip rules for a zone
curl http://localhost:3001/api/zones/{zone-id}/skip-rules

# Add a skip rule to a zone
curl -X POST http://localhost:3001/api/zones/{zone-id}/skip-rules \
  -H "Content-Type: application/json" \
  -d '{"rule_type":"rain_forecast","threshold_mm":5,"window_hours":24}'

# Update a skip rule
curl -X PUT http://localhost:3001/api/zones/{zone-id}/skip-rules/{rule-id} \
  -H "Content-Type: application/json" \
  -d '{"threshold_mm":8}'

# Delete a skip rule
curl -X DELETE http://localhost:3001/api/zones/{zone-id}/skip-rules/{rule-id}

Skip Preview Response

The skip preview endpoint returns per-zone evaluation before any runs fire:

{
  "evaluated_at": "2025-04-14T06:00:00Z",
  "weather_source": "cache",
  "weather_age_minutes": 12,
  "zones": [
    {
      "zone_id": "...",
      "zone_name": "Garden Beds",
      "scheduled_today": true,
      "will_skip": true,
      "skip_reason": "Rain forecast 12.4mm in next 24h exceeds threshold 5.0mm",
      "rule_type": "rain_forecast"
    },
    {
      "zone_id": "...",
      "zone_name": "Front Lawn",
      "scheduled_today": true
       
       
    
  

Environment Variables

Variable	Description	Default
DEFAULT_LATITUDE	Initial latitude loaded into settings	0
DEFAULT_LONGITUDE	Initial longitude loaded into settings	0
WEATHER_CACHE_TTL_MIN	Minutes before weather cache is considered stale	30

Set DEFAULT_LATITUDE and DEFAULT_LONGITUDE at first launch to avoid needing to manually configure Settings before skip rules can evaluate.

Troubleshooting

Weather data shows zeros or empty

1. Confirm coordinates are set: GET /api/settings - check latitude and longitude are non-zero
2. Test Open-Meteo directly: curl "https://api.open-meteo.com/v1/forecast?latitude=YOUR_LAT&longitude=YOUR_LON&daily=precipitation_sum&timezone=auto"
3. Check server logs for HTTP errors on the weather fetch

Zone ran despite rain forecast

1. Check skip preview before the scheduled run time: GET /api/weather/skip-preview
2. Confirm the skip rule is attached to the zone: GET /api/zones/:id/skip-rules
3. Confirm enabled is 1 on both the zone and the skip rule
4. Check that window_hours covers the time of rain: if rain is forecast at hour 30 but your window is 24, it will not trigger
5. Verify the weather cache was fresh at run time: check GET /api/weather for fetched_at

Zone skipped when it should not have

1. Check the skip_reason in run history: GET /api/runs?status=skipped
2. Adjust the skip rule threshold upward and re-evaluate
3. If the threshold seems correct, verify units: Open-Meteo returns mm, not inches

Weather fetch fails silently

When Open-Meteo is unreachable, the scheduler falls back to running as scheduled (safe-to-water default). Check server logs for WEATHER_FETCH_ERROR entries. No zones will be skipped if weather data cannot be refreshed within the cache TTL.