View Source

This page is currently a guideline for what a DD API 3.0 service should confirm to in order to be able to let Delft FEWS clients connect to it.

Delft-FEWS will construct request url's as follows:

<serverUrl>?$filter=parameter/quantity eq '<parameterId>' and parameter/parameter eq '<qualifierId>' and foi/code eq '<locationId>' and phenomenontime/beginposition ge <startTime> and phenomenontime/endposition le <endTime>

Where

<serverUrl> will be replaced by the server url configured in the FEWS import configuration
<parameterId> will be replaced by external parameter id, this will always be supplied
<qualifierId> will be replaced by external qualifier id, this is optional, when there is no external qualifier the and parameter/parameter eq '<qualifierId>' part of the url request will be left out
<locationId> will be replaced by external location id, this will always be supplied
<startTime> will be replaced by the start of the requested period according to the format: yyyy-MM-ddTHH:mm:ssZ this will always be supplied
<endTime> will be replaced by the end of the requested period according to the format: yyyy-MM-ddTHH:mm:ssZ this will always be supplied

There will not be a part in the url request to specify the desired time step of the data. In case the data returned will not be according to a consistent time step, a non-equidistant time step should be used within FEWS from which later on equidistant time series can be constructed if desired.

For service providers it is import to know they will always get parameter/quantity eq '<parameterId>' defined and optionally and parameter/parameter eq '<qualifierId>'. There is no direct need to understand the meaning of FEWS terminology external parameter id and external qualifier id. The service provider can let the data determine what needs to be filled in for it. It will be the task of administers of the FEWS system to make the external parameter id and external qualifier id match with the data.

From the response below the FEWS external parameter will be DEBIET, taken from:

"parameter": {
"procedure": "pb33fp7142",
"sensor": "DIVER_001",
"compartment": "BW",
"quantity": "DEBIET"
}

The FEWS external location id will be GWLICHAAM_ZAND_MS_01, taken from:

"featureOfInterest": {
"type": "Feature",
"id": "GWLICHAAM_ZAND_MS_01",

The times will be 2024-03-20T00:00:00 to 2024-03-20T23:00:00, taken from:

"result": {
"type": "Coverage",
"domain": {
"type": "Domain",
"axes": {
"t": { "values": [
"2024-03-20T00:00:00Z",

...
"2024-03-20T23:00:00Z"

The values will be taken from:

"ranges": {
"groundwaterLevel": {
"type": "NdArray",
"dataType": "float",
"values": [
-2.35, -2.36, -2.36, -2.37, -2.37, -2.38,
-2.38, -2.39, -2.39, -2.40, -2.40, -2.41,
-2.41, -2.42, -2.42, -2.41, -2.41, -2.40,
-2.40, -2.39, -2.38, -2.37, -2.36, -2.35

The quality flags will be taken from:

"quality": {
"type": "NdArray",
"dataType": "string",
"values": [
"VALID", "VALID", "VALID", "VALID", "VALID", "VALID",
"VALID", "VALID", "VALID", "VALID", "VALID", "VALID",
"VALID", "VALID", "VALID", "VALID", "VALID", "VALID",
"VALID", "VALID", "VALID", "VALID", "VALID", "VALID"
]

It must be taken into account that according to the JSON rules key-value pairs within the same object are allowed to be in any order.

So in the example below "resultTime": "2024-03-21T00:05:00Z", is also allowed to be before "phenomenonTime": {....},

Full example:

{
"@odata.context": "v3/observations/$metadata#Observations",
"values": [
{
"id": "obs_20240320_pb33fp7142",
"phenomenonTime": {
"beginPosition": "2024-03-20T00:00:00Z",
"endPosition": "2024-03-20T23:59:59Z"
},
"resultTime": "2024-03-21T00:05:00Z",
"parameter": {
"procedure": "pb33fp7142",
"sensor": "DIVER_001",
"compartment": "BW",
"quantity": "DEBIET"
},
"metadata": {
"wellProperties": {
"surfaceLevel": 2.45,
"wellDepth": 15.0,
"filterTop": -12.0,
"filterBottom": -13.0,
"tubeType": "HDPE",
"tubeDiameter": 0.032
}
},
"featureOfInterest": {
"type": "Feature",
"id": "GWLICHAAM_ZAND_MS_01",
"geometry": {
"type": "Polygon",
"coordinates": [[
[5.123, 52.345],
[5.234, 52.345],
[5.234, 52.456],
[5.123, 52.456],
[5.123, 52.345]
]]
},
"properties": {
"name": "Zand Maas - Diep grondwater",
"code": "NLGW0006",
"type": "GroundwaterBody",
"formation": "Formatie van Tegelen",
"aquiferType": "Confined",
"waterAuthority": "Provincie Noord-Brabant"
}
},
"result": {
"type": "Coverage",
"domain": {
"type": "Domain",
"axes": {
"t": { "values": [
"2024-03-20T00:00:00Z",
"2024-03-20T01:00:00Z",
"2024-03-20T02:00:00Z",
"2024-03-20T03:00:00Z",
"2024-03-20T04:00:00Z",
"2024-03-20T05:00:00Z",
"2024-03-20T06:00:00Z",
"2024-03-20T07:00:00Z",
"2024-03-20T08:00:00Z",
"2024-03-20T09:00:00Z",
"2024-03-20T10:00:00Z",
"2024-03-20T11:00:00Z",
"2024-03-20T12:00:00Z",
"2024-03-20T13:00:00Z",
"2024-03-20T14:00:00Z",
"2024-03-20T15:00:00Z",
"2024-03-20T16:00:00Z",
"2024-03-20T17:00:00Z",
"2024-03-20T18:00:00Z",
"2024-03-20T19:00:00Z",
"2024-03-20T20:00:00Z",
"2024-03-20T21:00:00Z",
"2024-03-20T22:00:00Z",
"2024-03-20T23:00:00Z"
] }
}
},
"ranges": {
"groundwaterLevel": {
"type": "NdArray",
"dataType": "float",
"values": [
-2.35, -2.36, -2.36, -2.37, -2.37, -2.38,
-2.38, -2.39, -2.39, -2.40, -2.40, -2.41,
-2.41, -2.42, -2.42, -2.41, -2.41, -2.40,
-2.40, -2.39, -2.38, -2.37, -2.36, -2.35
],
"unit": "m",
"referenceLevel": "NAP",
"observedProperty": {
"id": "grondwaterstand",
"definition": "http://vocab.example.org/parameters/grondwaterstand"
}
},
"quality": {
"type": "NdArray",
"dataType": "string",
"values": [
"VALID", "VALID", "VALID", "VALID", "VALID", "VALID",
"VALID", "VALID", "VALID", "VALID", "VALID", "VALID",
"VALID", "VALID", "VALID", "VALID", "VALID", "VALID",
"VALID", "VALID", "VALID", "VALID", "VALID", "VALID"
]
}
},
"referenceSystem": {
"type": "Link",
"href": "http://www.opengis.net/def/crs/EPSG/0/4326"
}
}
}
]
}