Deze pagina beschrijft de mogelijkheden om sensordata m.b.t. grondwater toe te voegen aan DOV.
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:
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".
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:
|
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 |
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": [] } |
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.
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.
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.
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 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:
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.
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
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. |
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 https://www.milieuinfo.be/confluence/pages/viewpage.action?pageId=142778128#Demo-projectCases-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.
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 |
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.
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).
Header: Content-Type: application/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).
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")
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.
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 |
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" } ] } |
Header: Accept: text/csv
Als antwoord zal een CSV-bestand gedownload worden.
Header: Accept: application/zip
Als antwoord zal een ZIP-bestand gedownload worden.
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 |
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.
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.
Header: Accept: application/zip
Als antwoord zal een ZIP bestand gedownload worden met vergelijkbare ZIP-bestanden zoals hierboven geschreven.