Informatie
Deze pagina werd gearchiveerd in 2023. Voor de meest recente versie, bekijk de bijgewerkte versie onder de tab 'Data aanleveren'.

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

Overzicht van alle beschikbare API-calls (klik op de link voor meer info):

GET /chucknorris → healthcheck
POST /dovinstrumentserver/appinstrument/search/instrumenten/ → oplijsting van alle bekende instrumenten. In de postbody kunnen volgende optionele parameters worden meegegeven:
- parameter instrumentTypeCode (optional) → filter instrumenten met deze instrumentTypeCode bv. {"instrumentTypeCode": "TMS"}
- parameter text (optional) → filter instrumenten waarin deze tekst voorkomt in de naam, serienummer, ..., bv. {"text": "diver_UA_"}
- parameter textmatchers (optional) → specifieert de velden waarin text zal gaan zoeken, bv. [ "SERIENUMMER", "REFERENTIE", "NAAM"]
- parameter matchers (optional) → geeft labels waarmee de instrumenten worden gefilterd, bv. ["GEKOPPELDE_INSTRUMENTEN", "ACTIEVE_INSTRUMENTEN", "NIET_ACTIEVE_INSTRUMENTEN", "NIET_GEKOPPELDE_INSTRUMENTEN" ]
/hfmetingen/instrumenten/
- POST /hfmetingen/instrumenten/ → aanmaken van een instrument
- GET /hfmetingen/instrumenten/{idOrPermkey} → info opvragen van één instrument
- PUT /hfmetingen/instrumenten/{idOrPermkey} → wijzigen van een bestaand instrument
- DELETE → method 'delete' not supported. Verwijder instrumenten via de webinterface.
/hfmetingen/instrumenten/{idOrPermkey}/sensoren
- GET → lijst opvragen van sensoren bij één instrument
/hfmetingen/instrumenten/{id}/sensordata (!nog te bevestigen of dit endpoint nog geldig is)
- GET → lijst opvragen van sensoren bij één instrument, met ook info over parameters, aantal datapunten, ...
/hfmetingen/instrumenten/{idOrPermkey}/sensoren/{sensorIdOrPermkey}/meetpunten
- GET → opvragen van datapunten bij één sensor
- POST → upload van 1 datapunt (synchroon), meerdere datapunten (asynchroon) of een csv-bestand (asynchroon)
- DELETE → verwijderen van datapunten
GET /hfmetingen/importlog/{id} → geeft de status van een import job
POST /hfmetingen/instrumentlink/ → instrument linken aan filter of bodemlocatie
GET /dovinstrumentserver/appinstrument/instrumenten/{id}/links/ → lijst opvragen van links bij een instrument (naar filter of bodemlocatie). Opgelet: werkt enkel met id, niet met permkey.
DELETE /hfmetingen/instrumentlink/{linkid}?comment=Geen%20commentaar → verwijderen van de link met het opgegeven linkid
GET /hfmetingen/meetreeksen/{domainObjectType}/{objectPermkey}/sensortypes → opvragen sensortypes bij een filter of bodemlocatie
GET /hfmetingen/meetreeksen/{domainObjectType}/{objectPermkey}/parameters/{parameterId}/meetpunten → opvragen van de meetreeksdata van een filter of bodemlocatie (als json, zip of csv)
GET /hfmetingen/meetreeksen/{domainObjectType}/{objectPermkey}/parameters/{parameterId}/sensortypes/{sensorIdentificatieCode}/meetpunten → ??
- onduidelijk wat dit precies kan. Mogelijks een schrijffout waarbij /parameters/{parameterId} weggelaten moet worden.
- Volgende parameters kunnen worden meegegeven: startDatum, eindDatum, type (gevalideerd, niet_gevalideerd)
GET /hfmetingen/meetreeksen/{FILTER_PERMKEY}/sensortypes/{SENSORTYPE_CODE}/meetpunten → onduidelijk of deze call nog werkt.

Nuttige API-calls voor bodem (geen documentatie beschikbaar):

Bodemlocaties:
- GET /dov-bodem-server/bodem/locatie/search/suggest?criteria={bodemlocatienaam}&maxresults=5 → opzoeken van bodemlocatie op naam (opgelet: kan meerdere resultaten geven, geeft [ ] indien niets gevonden)
- GET /dov-bodem-server/bodemlocatie/{PermKey} → info opvragen van één bodemlocatie (geeft 403 indien niet gevonden)
- DELETE /dov-bodem-server/bodemlocatie/{IDofPermKey}?comment=Geen%20commentaar → verwijdert één bodemlocatie
BodemSites:
- GET /dov-bodem-server/bodem/site/search/suggest?criteria={bodemsitenaam}&maxresults=5 → opzoeken van bodemsite op naam (opgelet: kan meerdere resultaten geven, geeft [ ] indien niets gevonden)
- DELETE /dov-bodem-server/bodemsite/{IDofPermKey}?comment=Geen%20commentaar → verwijdert één bodemsite
Opdrachten:
- GET /dov-proeven-server/opdracht/search/suggest?criteria=curieuze&maxresults=5 → opzoeken van opdracht op naam (opgelet: kan meerdere resultaten geven, geeft [ ] indien niets gevonden)
- DELETE /dov-proeven-server/opdrachten/{IDofPermKey}?comment=Geen%20commentaar → verwijdert één opdracht

API-calls voor codetabellen (geen documentatie beschikbaar):

...

.dov.vlaanderen.be/

...

filters/codetabellen/

...

methodepeilmeting

Image Removed

https://

...

services.dov.vlaanderen.be/

...

filters/codetabellen/debietmetermerk

...

Waarschuwing

title	Oudere pagina

Deze rest van deze pagina is een oudere versie van de API-documentatie 'sensordata grondwater', maar geeft een leesbare inleiding.

De meest recente handleiding is te vinden op

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

...

. Hierin zijn de meeste REST-calls terug te vinden, met hun beschikbare opties en attributen. Deze API-referentie wordt automatisch aangemaakt.

Inhoudsopgave

Inleiding

Basisprincipes

Hieronder enkel basisprincipes samengevat:

...

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 data afkomstig van alle sensoren van een bepaald type van de instrumenten gekoppeld aan de filter.

...

Informatie

icon	false

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:

...

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

...

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.

...

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.

...

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

...

Codeblok

title	Antwoord

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-zie 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;

...

Codeblok

title	URL

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;

...

Codeblok

title	URL

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

...

Codeblok

title	Mogelijk antwoord

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

...

Codeblok

title	URL

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

...

Pagina-navigatiestructuur

Versies vergeleken

Oude versie 9

Nieuwe versie Huidige

Uitleg

Inleiding

Basisprincipes

"Instrument" en "Sensor"

"Concept Meetreeks"

Dataformaat

Synchroon/Assynchroon opladen

Verwijderen van data

Updaten van data

Downloaden van sensordata/meetreeksen

REST-Ontsluitingen

Putten/filters: zoeken & aanmaken

Instrumenten/sensoren: zoeken & aanmaken

Use-Cases Demo project Hoog Frequente metingen

Demo 1: Healthcheck

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

Demo 3: Upload sensor data

1 datapunt

Meerdere datapunten

CSV-bestand

Controleer de status bij een assynchrone import

Demo 4: verwijder sensordata

Demo 5: Download data aan een sensor

Download in JSON formaat

Download in CSV formaat

Download in ZIP formaat

Demo 6: Download data aan een filter (meetreeksdata)

Download in JSON formaat

Download in CSV formaat

Download in ZIP formaat

Pagina-navigatiestructuur

Pagina historie

Versies vergeleken

Oude versie 9

Nieuwe versie Huidige

Uitleg

Inleiding

Basisprincipes

"Instrument" en "Sensor"

"Concept Meetreeks"

Dataformaat

Synchroon/Assynchroon opladen

Verwijderen van data

Updaten van data

Downloaden van sensordata/meetreeksen

REST-Ontsluitingen

Putten/filters: zoeken & aanmaken

Instrumenten/sensoren: zoeken & aanmaken

Use-Cases Demo project Hoog Frequente metingen

Demo 1: Healthcheck

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

Demo 3: Upload sensor data

1 datapunt

Meerdere datapunten

CSV-bestand

Controleer de status bij een assynchrone import

Demo 4: verwijder sensordata

Demo 5: Download data aan een sensor

Download in JSON formaat

Download in CSV formaat

Download in ZIP formaat

Demo 6: Download data aan een filter (meetreeksdata)

Download in JSON formaat

Download in CSV formaat

Download in ZIP formaat