Bekijk een uitgebreidere versie van deze documentatie via API documentatie op https://www.dov.vlaanderen.be/portaal/#DovIntroductionPage

https://www.dov.vlaanderen.be/portaal/?module=doc-api-instrument

https://www.dov.vlaanderen.be/portaal/api/instrument/api-guide.html


Deze pagina beschrijft de mogelijkheden om sensordata m.b.t. grondwater toe te voegen aan DOV.

Inleiding

Basisprincipes

Hieronder enkel basisprincipes samengevat:

De data wordt dus steeds gekoppeld aan een sensor van een instrument. Om deze data te koppelen moeten volgende gegevens gekend zijn:


"Instrument" en "Sensor"

 (star) Indien een instrument 2 sensoren bevat die bijvoorbeeld temperatuur opmeten: je kan geen 2 sensoren van hetzelfde type toevoegen. Echter, elke temperatuur die dit instrument zal meten, heeft normaal een andere functie. Het is altijd mogelijk om 2 types te definiëren in beheer die als meeteenheid °C hebben maar een andere parameternaam hebben. Bijvoorbeeld "Temperatuur" en "ReferentieTemperatuur".

"Concept Meetreeks"

Een meetreeks is een verzameling van data afkomstig van alle sensoren van een bepaald type van de instrumenten gekoppeld aan de filter.

Indien 1 of meerdere instrumenten gekoppeld zijn met een filter, en de instrumenten bevatten 1 of meerdere sensoren met data, wordt voor elk type sensor een meetreeks gevormd.

Bijvoorbeeld:


Instrument 1 met 2 sensoren met data: temperatuur en peilmetingen

Instrument 2 met 2 sensoren met data: luchtdruk en peilmetingen

Instrument 1 gekoppeld met Filter 1 in 2018

Instrument 2 gekoppeld met Filter 1 in 2019

Resulteert in 3 meetreeksen:

  • Een meetreeks van het type "peilmetingen" die data zal bevatten van 2018 en 2019
  • Een meetreeks van het type "Temperatuur" die data zal bevatten van 2018
  • Een meetreeks van het type "Luchtdruk" die data zal bevatten van 2019

Dataformaat

DOV verwacht ook een specifiek formaat waaraan elk datapunt moet voldoen. Elk datapunt moet volgende gegevens bevatten:

Men kan 1 datapunt of meerdere datapunten tegelijkertijd opladen naar DOV. Meerdere punten kunnen in de request zelf doorgestuurd worden of via een CSV-bestand. Het CSV bestand is dan een kommagescheiden bestand met op elke lijn 1 meetpunt. Bijvoorbeeld

2019-12-31T14:00:00.000+01:00,1029.375,1
2019-12-31T13:00:00.000+01:00,1027.375,0


Synchroon/Assynchroon opladen

Bij het opladen van 1 punt zal dat punt onmiddellijk toegevoegd worden aan DOV (synchroon). Bij meerdere punten (zowel in de body van een POST-request of via een CSV-bestand) zal de import assynchroon verlopen.

Te allen tijde kan de status van de assynchrone import bekeken worden. Deze status (in JSON-formaat) bevat volgende gegevens:

{
    "id": 263,
    "sensorId": 4,
    "uploadTime": "16-07-2020 12:05:34",
    "auteur": "Doe John",
    "bestand": {
        "code": "251",
        "beschrijving": "Testcsv.csv"
    },
    "status": "NIET_VERWERKT",
    "startVerwerking": null,
    "eindVerwerking": null,
    "aantalMeetpunten": null,
    "type": "UPLOAD_REST_CSV",
    "messages": []
}

Fouten en  waarschuwingen zullen ook verduidelijkt worden in 'Message'. Een voorbeeld van een validatiefout is 'Datum datapunt moet binnen datum in gebruik en datum uit gebruik van het instrument liggen.'

Verwijderen van data

Gegevens kunnen ook verwijderd worden van een sensor door een tijdsinterval mee te geven waartussen alle meetwaarden verwijderd worden.

Hiervoor zijn volgende inputgegevens nodig:

Indien de starttijd niet meegegeven is, zal alle data tot en met de eindtijd verwijderd worden. Indien de eindtijd niet meegegeven is, zal alle data vanaf de starttijd verwijderd worden. Indien geen tijd meegegeven is, zal alle data verwijderd worden. Indien zowel start- als eindtijd meegegeven wordt, zal alle data (grenzen incluis) binnen die periode verwijderd worden.

Updaten van data

Om gegevens te updaten, moeten de bestaande meetwaarden eerst worden verwijderd en vervolgens opnieuw worden toegevoegd.

Indien gegevens worden opgeladen die al waren toegevoegd, zal bij de upload een validatiefout als antwoord terug komen. Voorbeeld van dergelijke boodschap is 'Meetpunt "2020-09-16T01:00:00.000+02:00" bestaat reeds in de databank voor deze sensor'.

Downloaden van sensordata/meetreeksen

Er kan data aan een sensor of filter (meetreeks) opgehaald worden. Het resultaat kan een JSON, CSV of ZIP zijn. Een ZIP zal steeds CSV-bestanden bevatten met data gegroepeerd per maand.

Indien data aan een sensor gedownload wordt, zijn volgende gegevens nodig:

Indien data aan een filter (meetreeks) gedownload wordt, zijn volgende gegevens nodig:

In beide gevallen kunnen start en/of eindtijd meegegeven worden. Indien de starttijd niet meegegeven is, zal alle data tot en met de eindtijd verwijderd worden. Indien de eindtijd niet meegegeven is, zal alle data vanaf de starttijd verwijderd worden. Indien geen tijd meegegeven is, zal alle data verwijderd worden. Indien zowel start- als eindtijd meegegeven wordt, zal alle data (grenzen incluis) binnen die periode verwijderd worden.


REST-Ontsluitingen

De beschrijving van de REST API is terug te vinden via de swagger file: swagger_v03.yaml Deze kan geopend worden via https://editor.swagger.io/ of Postman (https://www.postman.com/)

Putten/filters: zoeken & aanmaken

Putten en filters kunnen in de DOV verkenner via de laag "Grondwaterlocaties" terug gevonden worden.

Aanmaken van putten en filters kan, indien de gebruiker de rechten heeft om een put of filter aan te maken, op twee manieren gebeuren:

Instrumenten/sensoren: zoeken & aanmaken

Indien de gebruiker rechten heeft kan op het DOV-portaal via een link "Beheer instrumenten" onder subtitel "Grondwater" een pagina geopend worden waar instrumenten kunnen aangemaakt en bekeken worden.
In een instrument-fiche kan een sensor aangemaakt worden.

Use-Cases Demo project Hoog Frequente metingen

Op de github-pagina van DOV (https://github.com/DOV-Vlaanderen/dov-services-quickstart) staat een demoproject dat kan helpen om via eigen code hoog frequente data naar DOV te zenden. De code van hoog frequente metingen staat onder het package "hfmetingen".

De demo-applicatie toont alle mogelijke situaties en deze zullen hieronder beschreven worden.

Hieronder zijn de productie URL's gebruikt. Er zijn ook url's voor


Demo 1: Healthcheck

Hier gebeurt een call om te controleren of de services beschikbaar en of de security in orde is (certificaten,...).

GET https://services.dov.vlaanderen.be/dovinstrumentserver/chucknorris


Chuck Norris is the reason Waldo is hiding.


Demo 2: Verkrijgen van een lijst van sensoren aan een instrument

Om meetdata toe te voegen is de permkey van het instrument en het ID van de sensor nodig. De permkey kan via de DOV-applicaties achterhaald worden (zie Instrumenten/sensoren:zoeken&aanmaken ), de sensorid's kunnen opgehaald worden via volgende call:


GET https://services.dov.vlaanderen.be/hfmetingen/instrumenten/{INSTRUMENT_PERMKEY}/sensoren


[
	{"code":"4","beschrijving":"Temperatuur sensor"},
	{"code":"2","beschrijving":"Luchtdruksensor"}
]

De code geeft het ID weer van de sensor.


Demo 3: Upload sensor data

Indien de instrument-permkey en sensor ID gekend zijn, kan meetdata geüpload worden naar DOV;

Een POST request moet gemaakt worden:

POST https://services.dov.vlaanderen.be/hfmetingen/instrumenten/{INSTRUMENT_PERMKEY}/sensoren/{SENSOR_ID}/meetpunten

1 datapunt

Header: Content-Type: application/json

Een json-body moet hier mee gestuurd worden:

[
 {
     "tijd": "2020-06-11T03:00:00.000+01:00",
     "waarde": 10,
     "status": "GEVALIDEERD"
 }
]


{
    "status": "OK",
    "aantal": 1,
    "foutmelding": "",
    "importLogId": null
}

1 punt wordt onmiddellijk verwerkt. De status "OK" duidt erop dat het punt succesvol geïmporteerd is.

Meerdere datapunten

Header: Content-Type: application/json

Een json-body moet hier mee gestuurd worden:

[
 {
     "tijd": "2020-06-11T01:00:00.000+01:00",
     "waarde": 10,
     "status": "GEVALIDEERD"
 },
 {
     "tijd": "2020-06-11T02:00:00.000+01:00",
     "waarde": 20,
     "status": "GEVALIDEERD"
 }
]

Een mogelijk antwoord is volgende:

{
    "status": "ASYNC",
    "aantal": 2,
    "foutmelding": "",
    "importLogId": 261
}

Dit antwoord geeft aan dat de punten assynchroon worden verwerkt. De importLogId is nodig om de status van de upload te achterhalen (zie verder).

CSV-bestand

Header: Content-Typeapplication/x-www-form-urlencoded

De body bevat een CSV-bestand.

Een mogelijk antwoord is volgende:

{
    "status": "ASYNC",
    "aantal": 1,
    "foutmelding": "",
    "importLogId": 263
}

Dit antwoord geeft aan dat de punten assynchroon worden verwerkt. De importLogId is nodig om de status van de upload te achterhalen (zie verder).


Controleer de status bij een assynchrone import

Indien een import assynchroon verloopt, kan de status achterhaald worden aan de hand van de importlogId die verkregen is bij het antwoord van de upload.

Een GET request kan gemaakt worden:

GET https://services.dov.vlaanderen.be/hfmetingen/importlog/{IMPORTLOG_ID}

Een mogelijk antwoord is:

{
    "id": 263,
    "sensorId": 4,
    "uploadTime": "16-07-2020 12:05:34",
    "auteur": "Doe John",
    "bestand": {
        "code": "251",
        "beschrijving": "Testcsv.csv"
    },
    "status": "NIET_VERWERKT",
    "startVerwerking": null,
    "eindVerwerking": null,
    "aantalMeetpunten": null,
    "type": "UPLOAD_REST_CSV",
    "messages": []
}

Waarbij de status duidt of het bestand al dan niet reeds verwerkt is. In dit geval is het bestand nog niet verwerkt (status = "NIET_VERWERKT")


Demo 4: verwijder sensordata

Een DELETE request kan uitgevoerd worden met als niet verplichte parameters (startDatum, eindDatum en type)

DELETE https://services.dov.vlaanderen.be/hfmetingen/instrumenten/{INSTRUMENT_PERMKEY}/sensoren/{SENSOR_ID}/meetpunten?startDatum=2020-05-11T01:00:00.000%2B01:00&eindDatum=2020-08-11T01:00:00.000%2B01:00&type=GEVALIDEERD

Een mogelijk antwoord is:

{
    "status": "OK",
    "aantal": 3,
    "foutmelding": null,
    "importLogId": null
}

Waarbij de status zegt dat de punten succesvol verwijderd zijn en het aantal zegt dat er in dit geval 3 punten verwijderd zijn.

Demo 5: Download data aan een sensor

Indien de instrument-permkey en sensor ID gekend zijn, kan meetdata gedownload worden van DOV;

Een GET request moet gemaakt worden met optionele parameters (startDatum, eindDatum en type)

Het type van download kan worden bepaald adhv de Accept-header.

GET https://services.dov.vlaanderen.be/hfmetingen/instrumenten/{INSTRUMENT_PERMKEY}/sensoren/{SENSOR_ID}/meetpunten?eindDatum=2020-08-11T01:00:00.000%2B01:00&type=GEVALIDEERD&startDatum=2020-05-11T01:00:00.000%2B01:00

Download in JSON formaat

Header: Accept: application/json


{
    "instrumentId": "1",
    "sensorId": 4,
    "meetdata": [
        {
            "tijd": "2020-06-11T00:00:00.000Z",
            "waarde": 10.0,
            "status": "GEVALIDEERD"
        },
        {
            "tijd": "2020-06-11T01:00:00.000Z",
            "waarde": 20.0,
            "status": "GEVALIDEERD"
        }
    ]
}

Download in CSV formaat

Header: Accept: text/csv

Als antwoord zal een CSV-bestand gedownload worden.

Download in ZIP formaat

Header: Accept: application/zip

Als antwoord zal een ZIP-bestand gedownload worden.


Demo 6: Download data aan een filter (meetreeksdata)

Om meetreeksdata te downloaden, moet de filter-permkey en id van het sensortype gekend zijn.

Om de mogelijke sensortypes aan een filter te bepalen kan een GET request uitgevoerd worden:


GET https://services.dov.vlaanderen.be/hfmetingen/meetreeksen/{FILTER_PERMKEY}/sensortypes

Met als mogelijk antwoord:

[
    {
        "code": "4016",
        "beschrijving": "Hydrostatische druk"
    },
    {
        "code": "4017",
        "beschrijving": "Temperatuur"
    }
]

De code van het sensortype is nodig voor verdere requests.

Om de data van een filter te downloaden moet een GET request gemaakt worden met optionele parameters (startDatum, eindDatum en type)

GET https://services.dov.vlaanderen.be/hfmetingen/meetreeksen/{FILTER_PERMKEY}/sensortypes/{SENSORTYPE_CODE}/meetpunten?startDatum=2015-02-11T01:00:00.000%2B01:00

Download in JSON formaat

Header: Accept: application/json


{
    "putPermkey": "2017-000011",
    "filterPermkey": "2015-000881",
    "filterNummer": "1",
    "sensorType": "Hydrostatische druk",
    "plotEenheid": "hPa",
    "links": [
        {
            "instrumentPermkey": "2020-000069",
            "sensorId": 70,
            "meetEenheid": "hPa",
            "van": "2020-02-06T23:00",
            "tot": null,
            "eersteDatapunt": "2020-02-08T00:00:00.000Z",
            "laatsteDatapunt": "2020-02-08T00:00:00.000Z",
            "aantalMeetpunten": 1
        }
    ],
    "meetdata": [
        {
            "tijd": "2020-02-08T00:00:00.000Z",
            "waarde": 0.0,
            "plotWaarde": 0.0,
            "status": "GEVALIDEERD"
        }
    ]
}

Dit antwoord is iets geavanceerder. Hier is ook te zien van welk instrument de meetdata afkomstig is.

Download in CSV formaat

Header: Accept: text/csv

Als antwoord zal een CSV bestand gedownload worden.

Put: 2017-000011
Filter: 2015-000881
SensorType: Hydrostatische druk
Instrument 2020-000069: 2020-02-07T00:00:00.000+01:00 - ...
2020-02-08T01:00:00.000+01:00,0.0,1

Ook deze zip is iets complexer met bovenaan enkele header-lijnen die meer info geven over de koppeling van waar de data afkomstig is.

Download in ZIP formaat

Header: Accept: application/zip

Als antwoord zal een ZIP bestand gedownload worden met vergelijkbare ZIP-bestanden zoals hierboven geschreven.