hourly weather and spray-condition forecast (#85)

* adding the push thi/fligh/spray flags to the setup of the FC jobs

This should avoid issues on the fetch_or_create methods accessing
position [0] in an empty list of the given activity type respose.

* Treat empty location responses from FarmCalendar, handle open-meteo error when connection lost (#14)

* Handle error on no internet

* Handle empty json response from FC

* Add a safer check on empty graph list

* Add farm name and parcel to the obs title and desc

* Eagerly fetch parcels from FC

* Add hourly forecast endpoint

* Use total precipitation (rain, showers, snow) sum of the preceding hour instead of just rain

* Catch exceptions and treat missing spray values

---------

Co-authored-by: Felipe Arruda Pontes <felipe.arrudapontes@maastrichtuniversity.nl>

Author: fedjo

src/api/api_v1/api.py

@@ -1,9 +1,10 @@
 from fastapi import APIRouter
-from .endpoints import auth, locations, history
+from .endpoints import auth, locations, history, forecast
 
 
 api_router = APIRouter()
 api_router.include_router(locations.router, prefix="/locations", tags=["locations"])
 api_router.include_router(auth.router, prefix="/auth", tags=["authentication"])
 api_router.include_router(history.router, prefix="/history", tags=["history"])
+api_router.include_router(forecast.router, prefix="/forecast", tags=["forecast-hourly"])
 

src/api/api_v1/endpoints/forecast.py

@@ -0,0 +1,167 @@
+"""
+Hourly forecast endpoints.
+
+Returns all 24 hours of the current day (past and future) plus the
+following days, one record per hour.  No past-hour filtering is applied
+so callers always receive a complete day timeline.
+
+Endpoints
+---------
+GET /api/v1/forecast/hourly/
+    Plain JSON – hourly weather data for ``days`` days (default 5).
+
+GET /api/v1/forecast/hourly/spray/
+    Hourly spray-condition assessment derived from the same hourly
+    forecast, evaluated for every single hour (not tri-hourly).
+"""
+
+import logging
+from typing import Dict, List
+
+from fastapi import APIRouter, Query, HTTPException
+
+from src.external_services.openmeteo import WeatherClientFactory
+from src.schemas.point import GeoJSONOut
+from src.schemas.history_data import HourlyObservationOut, HourlyResponse
+from src.schemas.spray import SprayForecastResponse
+from src.models.spray import SprayStatus
+from src import utils
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# ---------------------------------------------------------------------------
+# Hourly weather forecast
+# ---------------------------------------------------------------------------
+
+@router.get(
+    "/hourly/",
+    response_model=HourlyResponse,
+    summary="Hourly weather data – today (full day) + next days",
+)
+async def get_hourly_forecast(
+    lat: float = Query(..., description="Latitude", example=38.25),
+    lon: float = Query(..., description="Longitude", example=21.74),
+    days: int = Query(
+        5, ge=1, le=16,
+        description="Number of days (including today)",
+    ),
+):
+    """
+    Returns **hourly** weather data from 00:00 of today through 23:00
+    of the last forecast day.
+
+    Unlike the legacy ``/api/data/forecast5/`` endpoint:
+
+    * Resolution is **1 hour** (not 3 hours).
+    * **All hours of today** are included – both past and future –
+      so the caller always receives a complete timeline for the
+      current day.
+    * Data comes from the Open-Meteo Forecast API (no API key required).
+    """
+    client = WeatherClientFactory.get_provider()
+    try:
+        results = await client.get_hourly_forecast(lat, lon, days=days)
+    except Exception as e:
+        logger.error(f"Error fetching hourly forecast from Open-Meteo: {e}")
+        raise HTTPException(
+            status_code=502,
+            detail="Could not retrieve hourly forecast from Open-Meteo",
+        ) from e
+
+    return HourlyResponse(
+        location={"lat": lat, "lon": lon},
+        data=results,
+        source="open-meteo",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Hourly spray-condition forecast
+# ---------------------------------------------------------------------------
+
+@router.get(
+    "/hourly/spray/",
+    response_model=List[SprayForecastResponse],
+    summary="Hourly spray-condition forecast – today (full day) + next days",
+)
+async def get_hourly_spray_forecast(
+    lat: float = Query(..., description="Latitude", example=38.25),
+    lon: float = Query(..., description="Longitude", example=21.74),
+    days: int = Query(
+        5, ge=1, le=16,
+        description="Number of days (including today)",
+    ),
+):
+    """
+    Evaluates **hourly** spray conditions from 00:00 of today through 23:00
+    of the last forecast day.
+
+    Each hour is individually assessed for temperature, wind, humidity,
+    precipitation and delta-T to produce an ``optimal``, ``marginal``,
+    or ``unsuitable`` rating.
+
+    All hours of the current day (past and future) are included so the
+    caller always gets a complete day timeline.
+    """
+    client = WeatherClientFactory.get_provider()
+    try:
+        hourly_data = await client.get_hourly_forecast(lat, lon, days=days)
+    except Exception as e:
+        logger.error(f"Error fetching hourly forecast from Open-Meteo: {e}")
+        raise HTTPException(
+            status_code=502,
+            detail="Could not retrieve hourly forecast from Open-Meteo",
+        ) from e
+
+    location = GeoJSONOut(**{"type": "Point", "coordinates": [lat, lon]})
+
+    results: List[SprayForecastResponse] = []
+    for obs in hourly_data:
+        v = obs.values
+        temp = v.get("temperature_2m")
+        humidity = v.get("relative_humidity_2m")
+        wind_ms = v.get("wind_speed_10m")
+        precipitation = v.get("precipitation", 0.0) or 0.0
+
+        # Instead of skipping the hour entirely if one variable is missing, we could
+        # choose to evaluate spray conditions with the available data and mark the missing
+        # variables in the detailed status.
+        if temp is None or humidity is None or wind_ms is None:
+            logger.warning(f"Missing essential weather data for hour {obs.timestamp}: temp={temp}, humidity={humidity}, wind_ms={wind_ms}")
+            spray_condition = "unknown"
+            status_details = {
+                "temperature": temp if temp is not None else "missing",
+                "humidity": humidity if humidity is not None else "missing",
+                "wind_speed": wind_ms if wind_ms is not None else "missing",
+                "precipitation": precipitation,
+            }
+        else:
+
+            wind_kmh = wind_ms * 3.6  # convert m/s → km/h
+            temp_wet_bulb = utils.calculate_wet_bulb(temp, humidity)
+            delta_t = temp - temp_wet_bulb
+
+            spray_condition, status_details = utils.evaluate_spray_conditions(
+                temp, wind_kmh, precipitation, humidity, delta_t,
+            )
+
+        # Convert SprayStatus enum values to strings for the dict
+        detailed_status_str: Dict[str, str] = {
+            k: v.value if isinstance(v, SprayStatus) else str(v)
+            for k, v in status_details.items()
+        }
+
+        results.append(
+            SprayForecastResponse(
+                timestamp=obs.timestamp,
+                spray_conditions=spray_condition,
+                source="open-meteo",
+                location=location,
+                detailed_status=detailed_status_str,
+            )
+        )
+
+    return results

src/core/app.py

@@ -148,9 +148,12 @@ async def start_scheduler(app: Application):
                 app.state.fc_client = FarmCalendarServiceClient(app)
                 await app.state.fc_client.fetch_and_cache_locations()
                 await app.state.fc_client.fetch_and_cache_uavs()
-                await app.state.fc_client.fetch_or_create_thi_activity_type()
-                await app.state.fc_client.fetch_or_create_flight_forecast_activity_type()
-                await app.state.fc_client.fetch_or_create_spray_forecast_activity_type()
+                if config.PUSH_THI_TO_FARMCALENDAR:
+                    await app.state.fc_client.fetch_or_create_thi_activity_type()
+                if config.PUSH_FLIGHT_FORECAST_TO_FARMCALENDAR:
+                    await app.state.fc_client.fetch_or_create_flight_forecast_activity_type()
+                if config.PUSH_SPRAY_F_TO_FARMCALENDAR:
+                    await app.state.fc_client.fetch_or_create_spray_forecast_activity_type()
 
                 await scheduler.start_scheduler(app)
 

src/external_services/openmeteo.py

@@ -1,22 +1,55 @@
+import logging
+from fastapi import HTTPException
 import httpx
-from datetime import date, datetime
-from typing import List, Optional, Protocol
+from datetime import date, datetime, timezone
+from typing import Dict, List, Optional, Protocol, Union
 import os
 
 from src.core import config
 from src.schemas.history_data import DailyObservationOut, HourlyObservationOut
 
 
+logger = logging.getLogger(__name__)
+
+
 class WeatherProvider(Protocol):
-    async def get_hourly_history(self, lat: float, lon: float, start: date, end: date, variables: List[str]) -> List[HourlyObservationOut]:
+    async def get_hourly_history(
+            self, lat: float, lon: float, start: date, end: date, variables: List[str]
+    ) -> List[HourlyObservationOut]:
         ...
 
-    async def get_daily_history(self, lat: float, lon: float, start: date, end: date, variables: List[str]) -> List[DailyObservationOut]:
+    async def get_daily_history(
+            self, lat: float, lon: float, start: date, end: date, variables: List[str]
+    ) -> List[DailyObservationOut]:
+        ...
+
+    async def get_hourly_forecast(
+            self, lat: float, lon: float, days: int = 5
+    ) -> List[HourlyObservationOut]:
         ...
 
 
 class OpenMeteoClient:
     BASE_URL = "https://archive-api.open-meteo.com/v1/archive"
+    FORECAST_URL = "https://api.open-meteo.com/v1/forecast"
+
+    async def _fetch_data(self, params: dict, url: Optional[str] = None) -> dict:
+        """Fetch data from Open-Meteo API with error handling."""
+        target_url = url or self.BASE_URL
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.get(target_url, params=params, timeout=10.0)
+                response.raise_for_status()
+                return response.json()
+        except (httpx.NetworkError, httpx.ConnectError, httpx.TimeoutException) as e:
+            logger.error(f"Internet connection is not available: {e}")
+            raise HTTPException(
+                status_code=503,
+                detail="Internet connection is not available. Please cache data for the specified location"
+            ) from e
+        except httpx.HTTPStatusError as e:
+            logger.error(f"HTTP error: {e}")
+            raise e
 
     async def get_hourly_history(self, lat: float, lon: float, start: date, end: date, variables: List[str]) -> List[HourlyObservationOut]:
         params = {
@@ -28,11 +61,7 @@ async def get_hourly_history(self, lat: float, lon: float, start: date, end: dat
             "end_date": end.isoformat()
         }
 
-        async with httpx.AsyncClient() as client:
-            response = await client.get(self.BASE_URL, params=params)
-            response.raise_for_status()
-            data = response.json()
-
+        data = await self._fetch_data(params)
         timestamps = data["hourly"]["time"]
         results = []
 
@@ -52,11 +81,7 @@ async def get_daily_history(self, lat: float, lon: float, start: date, end: date
             "end_date": end.isoformat()
         }
 
-        async with httpx.AsyncClient() as client:
-            response = await client.get(self.BASE_URL, params=params)
-            response.raise_for_status()
-            data = response.json()
-
+        data = await self._fetch_data(params)
         timestamps = data["daily"]["time"]
         results = []
 
@@ -71,6 +96,75 @@ async def get_single_day_history(self, lat: float, lon: float, day: date, variab
         daily = await self.get_daily_history(lat, lon, day, day, variables.get("daily", []))
         return hourly, daily
 
+    # ---- Hourly forecast (Open-Meteo Forecast API) ----
+
+    # The list of hourly variables requested from the Open-Meteo Forecast API.
+    HOURLY_FORECAST_VARIABLES = [
+        "temperature_2m",
+        "relative_humidity_2m",
+        "dew_point_2m",
+        "apparent_temperature",
+        "precipitation",
+        "rain",
+        "snowfall",
+        "snow_depth",
+        "pressure_msl",
+        "surface_pressure",
+        "cloud_cover",
+        "wind_speed_10m",
+        "wind_direction_10m",
+        "wind_gusts_10m",
+        "visibility",
+        "uv_index",
+    ]
+
+    async def get_hourly_forecast(
+        self, lat: float, lon: float, days: int = 5
+    ) -> List[HourlyObservationOut]:
+        """
+        Fetch hourly weather data for today (all 24 h, past + future) plus
+        the next ``days−1`` days from the Open-Meteo **Forecast** API.
+
+        Returns one :class:`HourlyObservationOut` per hour (up to ``days * 24``
+        entries).  Past hours of the current day are **never** filtered out so
+        the caller always gets a complete day timeline.
+        """
+        params = {
+            "latitude": lat,
+            "longitude": lon,
+            "hourly": ",".join(self.HOURLY_FORECAST_VARIABLES),
+            "timezone": "auto",
+            "past_days": 0,
+            "forecast_days": days,
+        }
+
+        data = await self._fetch_data(params, url=self.FORECAST_URL)
+
+        if "hourly" not in data:
+            logger.warning("Open-Meteo returned no hourly forecast data")
+            return []
+
+        timestamps = data["hourly"]["time"]
+        results: List[HourlyObservationOut] = []
+
+        for i, t in enumerate(timestamps):
+            values: Dict[str, Union[float, None]] = {}
+            for var in self.HOURLY_FORECAST_VARIABLES:
+                if var in data["hourly"]:
+                    values[var] = data["hourly"][var][i]
+            results.append(
+                HourlyObservationOut(
+                    timestamp=datetime.fromisoformat(t),
+                    values=values,
+                )
+            )
+
+        logger.info(
+            "Open-Meteo hourly forecast: %d hours for (%s, %s), %d days",
+            len(results), lat, lon, days,
+        )
+        return results
+
 
 # Factory using environment variable
 class WeatherClientFactory: