Added API endpoints for listing download links and downloading coverage data

[ricardogsilva]

This PR implements API endpoints for listing and downloading forecast-related coverages.

Implementation is based on the strategy discussed in

#150 (comment)

There are two endpoints:

1. /api/v2/coverages/forecast-data - lists download links

   This allows filtering by means of the following query parameters, which all accept multiple values:

   • climatological_variable (tas, tasmin, pr, fd, etc.)
   • aggregation_period (30yr, annual)
   • climatological_model (model_ensemble, etc.)
   • scenario (rcp26, rcp45 etc.)

2. /api/v2/coverages/forecast-data/{coverage_identifier} - allows download of a coverage as a NetCDF file

   This endpoint accepts spatial and temporal subsetting parameters:

   • datetime accepts a string of the form start/end where start and end are either a date like 2024-01-01 or .. to indicate an open interval
   • coords accepts a polygon specified in WKT

Example usage:

Get all download links for the tas indicator, with an aggregation period of annual, a climatological model of model_ensemble and scenario of rcp45:

/api/v2/coverages/forecast-data?
    climatological_variable=tas
    &aggregation_period=annual
    &climatological_model=model_ensemble
    &scenario=rcp45
    &offset=0
    &limit=100

The result is like this:

{
    "meta": {
        "returned_records": 27,
        "total_records": 27
    },
    "links": {...},
    "coverage_download_links": [
        "http://localhost:8877/api/v2/coverages/forecast-data/tas_annual_absolute_model_ensemble-annual-forecast-model_ensemble-tas-absolute-rcp45-all_year",
        "http://localhost:8877/api/v2/coverages/forecast-data/tas_annual_absolute_model_ensemble_lower_uncertainty-annual-forecast-model_ensemble-tas-absolute-rcp45-lower_bound-all_year",
        "http://localhost:8877/api/v2/coverages/forecast-data/tas_annual_absolute_model_ensemble_upper_uncertainty-annual-forecast-model_ensemble-tas-absolute-rcp45-upper_bound-all_year",
        ...,
        "http://localhost:8877/api/v2/coverages/forecast-data/tas_seasonal_anomaly_model_ensemble_upper_uncertainty-annual-forecast-model_ensemble-tas-anomaly-rcp45-upper_bound-winter"
    ]
}

The resulting links list can be used by the frontend to show a list of possible downloads to the user.

When the user chooses a link, it can perform a request like this:

/api/v2/coverages/forecast-data/tas_annual_absolute_model_ensemble-annual-forecast-model_ensemble-tas-absolute-rcp45-all_year?
    coords=POLYGON ((13.3 45.2, 13.3 46.8, 12.1 46.8, 12.1 45.2, 13.3 45.2))
    &datetime=../2024-01-01

As shown above, the user can include the coords and datetime query parameters in order to request a spatial and temporal subset of the coverage.

The result of this request is a netcdf file with the coverage data, which can then be loaded in e.g. QGIS, as shown below:

Details

In order to allow caching, the spatial subsetting is done by adjusting the input to a well-known grid - this means that the result is always a spatial area that is slightly larger than what the client requested. This well-known grid is configurable in the settings and can even be set via env variables:

ARPAV_PPCV__COVERAGE_DOWNLOAD_SETTINGS__SPATIAL_GRID__MIN_LON=10.279
ARPAV_PPCV__COVERAGE_DOWNLOAD_SETTINGS__SPATIAL_GRID__MIN_LAT=44.697
ARPAV_PPCV__COVERAGE_DOWNLOAD_SETTINGS__SPATIAL_GRID__MAX_LON=13.979
ARPAV_PPCV__COVERAGE_DOWNLOAD_SETTINGS__SPATIAL_GRID__MAX_LAT=47.097
ARPAV_PPCV__COVERAGE_DOWNLOAD_SETTINGS__SPATIAL_GRID__NUM_ROWS=24
ARPAV_PPCV__COVERAGE_DOWNLOAD_SETTINGS__SPATIAL_GRID__NUM_COLS=37

Data download requests are proxied to the THREDDS server and use its NCSS service, which allows the temporal and spatial subsetting.

This PR does not include the caching functionality yet, but the plan is to introduce it later and leverage the fact that it will be possible to save the prepared netcdf files in a local cache and reuse them when a similar request arrives, thus avoiding hitting the THREDDS server again to prepare the same data. Using this static grid will hopefully help in reducing the number of individual processing steps. The image below shows the grid (blue) and how a client-requested bbox (green) is fitted to the grid and used as the actual NCSS spatial extent (red):

---

• fixes allow download of model data #150