Weather Forecasts
=================

HireNext retrieves forecast data from the **DestinE Extremes Digital Twin** (DE_330 project) via
the DESP Polytope RESTful API using the earthkit-data library.  Data covers **Western Europe** at
hourly resolution and is refreshed automatically on an **hourly schedule**.

Forecast data is **cached** on the backend.  You can check the cache status or trigger a manual
refresh from the admin panel if you hold the ``forecast_cache`` role.

Available parameters
--------------------

.. list-table::
   :header-rows: 1
   :widths: 25 20 55

   * - Parameter key
     - Unit
     - Description
   * - ``temperature``
     - °C
     - 2-metre air temperature.
   * - ``humidity``
     - %
     - 2-metre relative humidity.
   * - ``wind_u``
     - m s⁻¹
     - 10-metre eastward wind component.
   * - ``wind_v``
     - m s⁻¹
     - 10-metre northward wind component.
   * - ``pressure``
     - hPa
     - Mean sea-level pressure.
   * - ``precipitation``
     - mm h⁻¹
     - Total precipitation rate.

.. note::

   **Solar radiation** is also fetched from Polytope and used internally to compute the DLR
   severity index (see :doc:`dlr-severity`), but is not exposed as a selectable forecast
   parameter.

Requesting a forecast via the UI
---------------------------------

1. Select a span from the span list on the Dashboard.
2. Click **Request Forecast**.
3. A loading indicator appears while data is fetched and processed.
4. Charts update with forecast values for all coordinate points in your span, covering a
   **0–23 hour window** from the latest model run.

For a continental overview of DLR conditions, navigate to the **Severity Map** page
(see :doc:`dlr-severity`).

Requesting a forecast via the API
----------------------------------

**Full forecast**

.. code-block:: bash

   curl -X POST "https://hirenext.dev.desp.space/backend/api/v1/forecast/" \
     -H "Cookie: access_token=<your-token>" \
     -F "file=@/path/to/coords.csv" \
     -F "parameters=temperature,wind_u,wind_v" \
     -F "forecast_days=3"

**Span-based forecast** (no file upload needed if the span is already saved)

.. code-block:: bash

   curl -X POST "https://hirenext.dev.desp.space/backend/api/v1/forecast/span/{span_id}" \
     -H "Cookie: access_token=<your-token>" \
     -F "parameters=temperature,wind_u,wind_v" \
     -F "forecast_days=3"

The ``forecast_days`` parameter accepts values from 1 to 7.  The response is a JSON object
containing timestamps and per-point forecast values.  See :doc:`api-reference` for the full schema.

Cache management (admin)
-------------------------

Users with the ``forecast_cache`` role can:

* **GET** ``/api/v1/forecast/cache/status`` — view when the cache was last updated.
* **POST** ``/api/v1/forecast/cache/refresh`` — trigger an immediate re-fetch from Polytope.