geobeyond / Arpav-PPCV-backend

Backend di Piattaforma Proiezioni Climatiche per il Nord-Est.
Creative Commons Attribution 4.0 International
0 stars 1 forks source link

Implement API endpoints for querying data #68

Closed ricardogsilva closed 4 months ago

ricardogsilva commented 5 months ago

Things that would be helpful to have:

A redesigned API would look like this:

GET /v2/api/coverages/time-series/{coverage-identifier}?
  coords={wkt}&
  datetime={datetime}&
  include_smoothed_data={smoothing_algorithm}&
  include_uncertainty=true&
  include_closest_observation_station=true&
  include_trendline_a=true&
  include_trendline_b=true&

The response would be a flat list of measurements, with suitable labels:

[
  {
    "timeseries": "tas_mean",
    "datetime": "1982-01-01T00:00:00Z",
    "value": 5.2, 
  },
  {
    "timeseries": "tas_mean_smoothed",
    "datetime": "1982-01-01T00:00:00Z",
    "value": 5.1, 
  },
  {
    "timeseries": "tas_mean-uncertainty_upper_bound",
    "datetime": "1982-01-01T00:00:00Z",
    "value": 7.2,
  },
  {
    "timeseries": "tas_mean-uncertainty_lower_bound",
    "datetime": "1982-01-01T00:00:00Z",
    "value": 4.7,
  },
{
    "timeseries": "tas_mean-trendline_a",
    "datetime": "1982-01-01T00:00:00Z",
    "value": 5.0,
  },
{
    "timeseries": "station1",
    "datetime": "1982-01-01T00:00:00Z",
    "value": 4.9,
  }
]

Alternatively, the response may be a CoverageJSON object, but this needs a bit further investigation

ricardogsilva commented 5 months ago

Some of the additional data series, like for specific types of trendlines, would need to accept additional runtime parameters (ex: in the start year, end year, significance of values, etc.).

gmassaroarpav commented 5 months ago

Please, add also:

ricardogsilva commented 5 months ago

Upon further analysis of requirements, an alternative design has been chosen:

Time series for observations data

Chart data for observations data has the following requirements:

With these requirements in mind, an API endpoint for requesting observation-related time series will look like this:

/api/v2/observations/{station_id}/time-series/{observation-variable-identifier}?
  datetime={datetime}&
  include_observations_data={true/false}&
  smoothing_algorithm={smoothing_algorithm}&
  include_decade_aggregation={true/false}&
  include_mann_kendall_trend={true/false}&
  mann_kendall_trend_start_year={mann_kendall_start_year}&
  mann_kendall_trend_end_year={mann_kendall_end_year}

Where:

The API response would be a JSON object of the form:

{
  "station_id": "{station_id}",
  "mann_kendall_trend": {
    "slope": 0.6,
    "intercept": 3.4,
    "significance": 0.9
  } 
  "values": [
    {
      "value": 5.6,
      "series": "tas_mean",
      "date": "1980-05-01"
    },
    {
      "value": 5.7,
      "series": "tas_mean",
      "date": "1980-06-01",
    },
    {
      "value": 5.4,
      "series": "mann_kendall_trend",
      "date": "1980-06-01",
    },
     {
      "value": 5.4,
      "series": "decade-1981-1990",
      "date": "1981-01-01",
    }
  ]
}

Time series for model data

Chart data for model data has the following requirements:

With these requirements in mind, an API for coverage-related charts will look like this:

/api/v2/coverages/time-series/{coverage-identifier}?
  coords={wkt}&
  datetime={datetime}&
  include_coverage_data={true/false}&
  include_observations_data={true/false}&
  coverage_data_smoothing={smoothing_algorithm}&
  observations_data_smoothing={smoothing_algorithm}&
  include_coverage_uncertainty={true/false}&
  include_coverage_related_data={true/false}&

Where:

The API response would be a JSON list of the form:

[
  {
    "value": 5.4
    "series": "tas_mean",
    "date": "1980-01-01",
  },
  {
    "value": 5.7
    "series": "tas_mean-uncertainty_upper_bound",
    "date": "1980-01-01",
  }
]
gmassaroarpav commented 5 months ago

The API response for observational data timeseries would be a JSON object of the form: { "station_id": "{station_id}", "mann_kendall_trend": { "slope": 0.6, "intercept": 3.4, "significance": 0.9 } "values": [ { "value": 5.6, "series": "tas_mean", "date": "1980-05-01" }, { "value": 5.7, "series": "tas_smooth", "date": "1980-06-01", }, { "value": 5.4, "series": "mann_kendall_trend", "date": "1980-06-01", }, { "value": 5.4, "series": "decade-1981-1990", "date": "1981-01-01", } ] }

The API response for model data timeseries would be a JSON list of the form: [ { "value": 5.4 "series": "tas_mean", "date": "1980-01-01", }, { "value": 5.7 "series": "tas_mean-uncertainty_upper_bound", "date": "1980-01-01", }, { "value": 5.7 "series": "tas_mean-uncertainty_lower_bound", "date": "1980-01-01", }, { "value": 5.7 "series": "tas_mean_smoothed", "date": "1980-01-01", }, { "value": 5.7 "series": "tas_mean_related_data", "date": "1980-01-01", } ]

Note: tas_mean is the ensemble mean and could include the uncertainty (tas_mean-uncertainty_upper_bound, tas_mean-uncertainty_lower_bound). tas_mean_related_data are the other 5 models related to the ensemble mean; these 5 models have not associated an uncertainty.

ricardogsilva commented 4 months ago

with the recent merge of #96 we can close this