Deze pagina beschrijft de mogelijkheden om hoogfrequente data toe te voegen aan DOV.

Inleiding

Basisprincipes

Hieronder enkel basisprincipes van hoogfrequente data samengevat:

• Hoog frequente data 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.

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

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

Bijvoorbeeld:

Dataformaat

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

• Datum/tijd met tijdzone van het datapunt (yyyy-mm-ddThh:mm:ss.nnnnnn+|-hh:mm) bijvoorbeeld 2019-12-31T14:00:00.000+01:00
• Sensorwaarde (in de eenheid die in DOV voor die sensor geregistreerd is). Bijvoorbeeld 1029.375. De eenheid wordt getoond in de sensor-tabel op de instrument-fiche in kolom "Meeteenheid".
• Waarde die aangeeft of de waarde gevalideerd is of niet gevalideerd is. 1 = gevalideerd, 0 = niet gevalideerd.

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": []
}

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

Hiervoor zijn volgende inputgegevens nodig:

• DOV-permkey van het instrument (verplicht)
• DOV-id van de sensor (verplicht)
• Starttijd (niet verplicht)
• Eindtijd (niet verplicht)

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.

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

• DOV-permkey van het instrument
• DOV-id van de sensor ( Merk op dat een sensor door heen de tijd aan meerdere filters gekoppeld kan zijn. Je krijgt dus alle gegevens door deze sensor gemeten onanfhankelijk van de koppeling met de filter.)

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

• DOV-permkey van de filter,
• DOV-id van het sensortype (Merk op dat doorheen de tijd meerdere sensoren aan de filter gekoppeld kunnen zijn. Alle gegevens van sensoren die waarden van het gekozen senortype kunnen opmeten worden gebundeld.)

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:

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

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

• 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,...).

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

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

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.