...

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

Inleiding

Basisprincipes

Hieronder enkel basisprincipes van hoogfrequente data samengevat:

• Hoog frequente data Data met hoge meetfrequentie is steeds gekoppeld aan een sensor van een instrument. Bijvoorbeeld een druksensor van een barologger of een druksensor van een diver die de hydrostatische druk meet.
• Een instrument kan op elk moment aan minimum 0 en maximum 1 filter gekoppeld zijn. In de tijd kan een instrument aan meerdere filters gekoppeld worden.
• Een meetreeks is de verzameling van hoog frequente data aan een filter van een bepaald type sensor voor een bepaalde periode. Deze data kan afkomstig zijn van verschillende instrumenten die dat type sensor bevatten en in de tijd aan de filter gekoppeld zijn geweest.

...

• DOV-permkey van het instrument.
• DOV-id van de sensor.

"Instrument" en "Sensor"

• Het instrument is een fysiek meettoestel.
• Een instrument kan aan 1 of meerdere filters gekoppeld worden, maar niet in dezelfde periode.
• Een filter kan op een bepaald moment maar maximaal aan 1 instrument gekoppeld zijn.
• Een instrument kan meerdere periodes aan een filter gekoppeld worden. Bijvoorbeeld in januari en in maart.
• Een instrument kan 1 of meerdere sensoren bevatten van een bepaald type.
  
  • Bijvoorbeeld een instrument kan 1 luchtdruksensor bevatten en een temperatuursensor.
  • Een instrument kan ook een afgeleide sensoren bevatten, bijvoorbeeld peilmetingen. Peilmetingen zijn een berekende waarde.
  • Aan een instrument kunnen verschillende sensoren hangen als ze maar telkens van een ander type zijn. Je kan dus niet 2 sensoren van het type "Temperatuur" koppelen met een instrument.
  
  

  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 hoogfrequente 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 hoogfrequente data, wordt voor elk type sensor een meetreeks gevormd.

...

Dataformaat

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

...

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.

...

• status: De status van de import. Mogelijke waarden zijn
  • NIET_VERWERKT
  • IN_VERWERKING
  • VERWERKT_MET_FOUTEN
  • VERWERKT_ZONDER_FOUTEN
  • VERWERKT_MET_WAARSCHUWINGEN
  • VALIDATIE_MET_FOUTEN
  • VALIDATIE_ZONDER_FOUTEN
  • VALIDATIE_MET_WAARSCHUWINGEN

Verwijderen van data

Gegevens kunnen ook verwijderd worden van een sensor door een tijdsinterval mee te geven waartussen alle meetwaarden verwijderd 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.

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.

...

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.

...

• Via de DOV-applicatie vanuit het portaal "Nieuwe put" om een nieuwe put aan te maken, vanuit de put-fiche kan een nieuwe filter aangemaakt worden.
• Via XDOV: Op basis van een XML gestructureerd volgens een gekend formaat in DOV kan een put en/of filter toegevoegd worden aan DOV.

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".

...

• oefen: https://services-oefen.dov.vlaanderen.be

Demo 1: Healthcheck

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

...

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 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:

...

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;

...

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

1 datapunt

Header: Content-Type: application/json

...

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

Meerdere datapunten

Header: Content-Type: application/json

...

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-Type: application/x-www-form-urlencoded

...

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.

...

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)

...

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;

...

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.

...

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

...

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.

...

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

...