Skip to content

Hydro API

Jump to bottom
Mikkel Stensgaard edited this page Sep 17, 2024 · 20 revisions

Overview

This API provides capabilities for managing hydrological Stations, Measurement Points, Measurements, and Results, including:

  • Create, update, and query hydrological Stations
  • Manage measurement points associated with Stations
  • Add, update, and delete Measurements
  • Query for Measurements with different filters

Authentication & Authorization

The endpoints support authentication using either client credentials or authorization code flow. For system-system integrations, using client credentials is the recommended approach.

Users working directly with the Hydro API, e.g. from script or command line, may use authorization code flow with their existing user account.

The following claims are necessary, to authenticate and authorize with the Hydro API:

Type Usage
sub Unique identifier for the caller
name Name identifying the caller
vat The organizational context
role miljoe_vanda_write, miljoe_vanda_operator, or miljoe_vanda_admin

Endpoints

Environment IdP Endpoint Swagger Usage
TEST https://log-in.test.miljoeportal.dk https://vandah.test.miljoeportal.dk/api/ https://vandah.test.miljoeportal.dk/api/swagger/index.html Internal test environment
DEMO https://log-in.test.miljoeportal.dk https://vandah.demo.miljoeportal.dk/api/ https://vandah.demo.miljoeportal.dk/api/swagger/index.html External test environment. E.g. for operators to test integrations.
PROD https://log-in.miljoeportal.dk https://vandah.miljoeportal.dk/api/ https://vandah.miljoeportal.dk/api/swagger/index.html Used for production

Use Cases

The Swagger endpoint describes the purpose of each methods in the Hydro API. The following details specific, common use cases for the Hydro API.

Get a List of Existing Stations

Required Roles None

To get a list of existing Hydrometry stations, call GET /stations

It supports several query parameters to filter the returned list. See swagger for details.

Create a Station

Required Roles miljoe_vanda_admin or miljoe_vanda_operator

Request

A station is created with the following request object.

{
  "operatorStationId": "string",
  "locationTypeSc": 0,
  "stationOwnerCvr": "string",
  "operatorCvr": "string",
  "name": "string",
  "description": "string",
  "location": {
    "x": 0,
    "y": 0,
    "datum": "string"
  },
  "waterAreaNr": "string",
  "measurementPointTypeSc": 0
}

operatorStationId is an optional external reference to the Station, e.g. if the Station is being run and managed by an Operator. If the Station owner is also managing the station, then this property should not be set. Note that this property if defined, must be globally unique to Vanda.

locationType stancode list SC1002 item reference to the type of location. Valid values are Valid options are {"Ej Oplyst" (SC1002:0),"Vandløb" (SC1002:1), "Sø" (SC1002:2), "Dræn" (SC1002:5), "Pumpestation" (SC1002:22)}

stationOwnerCvr is the CVR of the organization owning the station. It must be the CVR number of the organization, with "DK" prepended. E.g. DK12345678. This will never be th CVR of an Operator.

operatorCvr If the Station is being managed and run by an external organization, then this should be set to the CVR of that organization. It must be different from stationOwnerCvr.

name of the Station

description of the Station

location of the station. Must be provided as x, and y coordinates in UTM ETRS89 32N.

waterAreaNr reference to the water area number where the Station is located. The field is mandatory. If the waterAreaNr is unknown, set the value to 77000000.

measurementPointTypeSc stancode list SC1002 item reference to the type of Measurement Point location.

  • IF Station.LocationType != "Pumpestation" (SC1002:22) THEN must select MeasurementLocationType to use for the MeasurementPoint, that is created. Valid options are {"Ej Oplyst" (SC1002:0),"Vandløb" (SC1002:1), "Sø" (SC1002:2), "Dræn" (SC1002:5)}

Response

The response is the Vanda station number for the created Station.

{
  "stationId": "string"
}

The stationId is globally unique in Vanda, and never re-used.

Add Measurements To a Station

Required Roles miljoe_vanda_write, miljoe_vanda_admin, or miljoe_vanda_operator

Request

Measuremenst are added to a station with the following request object.

{
  "station": {
    "id": "string",
    "operatorStationId": "string"
  },
  "measurementPointNumber": 0,
  "examinationTypeSc": 0,
  "loggerId": "string",
  "parameterSc": 0,
  "unitSc": 0,
  "transactionBased": true,
  "measurements": [
    {
      "formulaId": "string",
      "measurementDateTime": "2023-10-13T04:50:33.370Z",
      "result": 0,
      "reasonCodeSc": 0
    }
  ]
}

station either Vanda station number or external reference to the station.

measurementPointNumber is the number (1 or 2) for the Measurement Point on which the `Measurement was taken.

examinationTypeSc stancode list SC1101 item refence to the type of Examination this Measurement is. Valid examination types are 21, 22, 24, 25, and 27. See the stancode list for further details about each examination type.

loggerId optional reference to the id of the logger used to collect the measurement.

parameterSc stancode list SC1008 item reference to the parameter for the Measurement. Valid parameters depend on the type of Examination. See later section.

unitSc stancode list SC1009 item reference to the unit for the Measurement. Valid units depend on the paramater and type of Examination. See later section.

transactionBased determines how a batch should be comitted. Individually (false) or together (true). If creating 10 measurements, setting transactionBased=true, and one measurement in the batch cannot commit, then the whole batch is rejected. Setting transactionBased=false, and only the single measurement is rejected.

measurements a list of Measurement to create. Currrently, there is a limit 1000 measurements in a single request to ensure performance.

  • measurementDateTime the date and time of the measurement. Must be provided as a datetime offset. Must be defined without second component as an UTC timestamp in the RFC 3339 date+time format. For example '2023-09-21T14:34Z'
  • result value. Note that result values are rounded to a number of decimals, when they are stored. The number of decimals depend on the examination type.
  • reasonCodeSc stancode list SC1188 item reference to the Activity this Result relates to. Valid options, depend on the type of Examination. See later section.

Response

The response is an object with information about the result of the transaction.

{
  "created": "2023-10-13T04:50:33.382Z",
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "successful": [
    {
      "timestamp": "2023-10-13T04:50:33.382Z",
      "action": "string"
    }
  ],
  "failed": [
    {
      "timestamp": "2023-10-13T04:50:33.382Z",
      "isSuccess": true,
      "errorCode": 0,
      "errorMessage": "string"
    }
  ]
}

created the date and time of the transaction.

transactionId the id of the transaction. Useful for debugging, or if contacting DMP Support with an problem about using the Hydro API.

successful a list of timestamps for Measurements that were successfully committed.

failed a list of timestamps for Measurements that were not committed, including a description of why it was not committed.

  • isSuccess is true if the Measurement can be comitted, and false if it cannot. In case the POST is done with transactionBased=true, then this attribute helps you identify which specific Measurements are causing the batch to fail.

Update Existing Measurements

Required Roles miljoe_vanda_write, miljoe_vanda_admin, or miljoe_vanda_operator

It is possible to update the Result value for a Measurement. It is not possible to update other attributes. Instead, delete the Measurement and create a new one with correct attributes.

A Measurement is identified by the measurementDateTime rounded to nearest minute.

When identifying which existing Measurement to update, Hydro API will first round, the provided measurementDateTime to the nearest minute, and use that to identify the corresponding measurement.

If attempting to batch update multiple Measurements, and several measurementDateTime in the request object rounds to the same, nearest dateTime, by minute, the request will be rejected.

Request

Measurement `Result values are updated with the following request object:

{
  "station": {
    "id": "string",
    "operatorStationId": "string"
  },
  "measurementPointNumber": 0,
  "examinationTypeSc": 0,
  "transactionBased": true,
  "results": [
    {
      "measurementDateTime": "2023-10-13T06:02:57.621Z",
      "result": 0,
      "reasonCodeSc": 0
    }
  ]
}

station vanda station number or external reference for the Station on which the Measurement should be updated. Since datetime rounded to nearest minute is used as key for the Measurement it is necessary to know the Station` to scope where to perform the update.

measurementPointNumber the number for the Measurement Point where the Measurement should be updated. Same reason as for supplying Station.

examinationTypeSc the type of Examination, this Measurement is about, since there can be multiple different Examinations on a Measurement Point.

results a list of Result values to update.

  • measurementDateTime of the Result value. This will be rounded to nearest minute and used as compound key together with {station, measurement point, examination type} to identify the Measurement to update the Result on. Note that this must be the date time of the Measurement to update. Not the created date of the Result value to update. Must be defined without second component as an UTC timestamp in the RFC 3339 date+time format. For example '2023-09-21T14:34Z'
  • result the new value. The update will be ignored, if it is identical to the existing result. Note that result values are rounded, when they are stored, and identity is compared using rounded values.
  • reasonCodeSc stancode list SC1188 item reference to the Activity this Result relates to. Valid options, depend on the type of Examination. See later section.

Response

Same response object as for creating Measurements.

Errors

The Hydro API follows standard conventions for setting HTTP codes according to result.

In general, there are three status code ranges you can expect:

  • 2xx status means success
  • 4xx errors relate to the provided information. E.g. lack of access (roles) or bad data.
  • 5xx errors are typically internal server errors. Something that causes a transaction to fail.

Methods that take a list as input are indicated with a plural s in the name, e.g. POST /measurements. These methods will return a response object with information about which list items could be processed, and which could not. In these cases, the API will return status 200 because the transaction as defined succeeded, but several list items may still have failed to commit.

See a detailed description of this response object in POST /measureemnts.

Mapping Between Examination, Parameter, and Unit

ExaminationType (SC1101) Parameter (SC1008) Unit (SC1009) Min Max Decimals1 Minimum Interval (minutes) 2
Elevation Level (21) (439) m (63) -15 170 1 5
Scale Pole Level (22) Water Level (1233) cm (19) -1.500 10.000 1 5
Water Level (25) Water Level (1233) cm (19) -1.500 10.000 1 5
Water Flow (27) Water Flow (1155) l/sek (55) - - 1 5
Measured Water Flow (24) Water Flow (1155) l/sek (55) - - 1 5
Oxygen (28) Oxygen (50) mg/l (1) 0 - 1 60
Temperature (29) Temperature (1154) Grader C (29) -20 50 1 60
Groundwater Level Field Measurement (30) Water Level (1233) m (63) -5 150 3 5
Groundwater Level (31) Water Level (1233) m (63) -5 150 3 5
  1. The API rounds to a number of decimals which depends on the examination type.
  2. Minimum interval between measurements to avoid excessive amounts of data.

Mapping Between Examination and Reason

Item Reason Elevation Level (21) Scale Pole Level (22) Measured Water Flow (24) Water Level (25) Waterflow (27) Oxygen (28) Temp
(29)		 Groundwater Level Measured (30) Groundwater Level (31)
0 Ej oplyst X X X X
1 Migreret X X X X X X
2 Ny skalapæl X X X
3 Kotekontrol X X X
4 Estimeret X X X X X X
5 Måling X X X X
6 Stangmåling X X X
7 Vademåling X X X
8 Dronebåd X X X
9 Opspænding X X X
10 Litermål X X
11 Skønnet vandføring X X
12 Section by section X X
13 Rørmåling X X
14 Flyder X X X X
15 Fløjte X X X X
16 Manometer X X X X
17 Nedstik X X X X
18 Nyt fixpunkt

Defined Concepts

Station An observable location. A Station has a geographic location (x and y coordinate), and one or two Measurement Points where Measurements are taken.

Station Owner Is the Organization that owns a Station. This Organisation is implicitly the Data Owner for all Measurement registered on the Station.

Operator Is an Organization that creates measurements on behalf of an Station Owner. Operator and Station Owner cannot be the same Organization (CVR). If Station Owner itself creates the Measurements on a Station, then the Station does not have an Operator, and the field is empty.

Measurement Point The specific place, on a Station where Measurements are taken. A Measurement Point` has its own geographic location, for its specific place.

Logger Used to collect Measurements.

Examination The act of collecting Measurements from a Measurement Point on a Station. An Examination starts on the date of the first Measurement and ends on the date of the last `Measurement.

Measurement is taken, when a Result is collected. A Measurement has a Result value, and associated metadata, including Parameter and `Unit.

Result The meaured value of a Measurement.

Clone this wiki locally