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

Overzicht van beschikbare API-endpoints

Onderstaande lijst geeft een overzicht van de beschikbare endpoints in de REST-API Instrumenten. Klik op de link voor meer info. 

De meest recente handleiding is te vinden op https://www.dov.vlaanderen.be/portaal/api/instrument/api-guide.html. Hierin zijn de meeste onderstaande endpoints terug te vinden, met hun beschikbare opties en attributen. Deze API-referentie wordt automatisch aangemaakt. In de onderstaande lijst zijn er ook een aantal endpoints terug te vinden, die nog niet gedocumenteerd staan in de API-referentie, maar die wel nuttig kunnen zijn bij het uitwerken van scripts.

API-endpoint Instrument

  • GET /chucknorris → healthcheck (is de server beschikbaar?)
  • GET /dovkernserver/actoren/0 → healthcheck (werkt mijn certificaat correct?)
  • POST /dovinstrumentserver/appinstrument/search/instrumenten/ → oplijsting van alle bekende instrumenten.
    • In de postbody kunnen volgende parameters worden meegegeven:
      • parameter textmatchers (optional) → specifieert de velden waarin text zal gaan zoeken, bv. [ "SERIENUMMER", "REFERENTIE", "NAAM"]. Opgelet: dit attribuut is verplicht en moet minstens 1 waarde bevatten, als je filtert op text, maar ook als je filtert op matchers. Zonder dit attribuut wordt er NIET gefilterd, en krijg je dus de volledige lijst van instrumenten. Als je echter filtert op instrumentTypeCode, mag dit veld NIET toegevoegd worden of moet het leeg zijn. 
      • parameter instrumentTypeCode (optional) → filter instrumenten met deze instrumentTypeCode bv. {"instrumentTypeCode": "TMS"} of {"instrumentTypeCode": "DIV"}
      • parameter text (optional) → filter instrumenten waarin deze tekst voorkomt in de naam, serienummer, ..., bv.  {"text": "diver_UA_"}
      • parameter exactTextMatch (optional) → True/False, zoeken naar een deel van een textveld, of enkel de volledige inhoud vergelijken (default = False). 
      • parameter matchers (optional) → geeft labels waarmee de instrumenten worden gefilterd, bv. ["GEKOPPELDE_INSTRUMENTEN", "ACTIEVE_INSTRUMENTEN", "NIET_ACTIEVE_INSTRUMENTEN", "NIET_GEKOPPELDE_INSTRUMENTEN" ] (default= []). Opgelet: dit attribuut moet samen gebruikt worden met ofwel attribuut textmatchers (met minstens 1 listelement) ofwel met attribuut instrumentTypeCode. Anders wordt de volledige lijst gegeven. 
    • vb volledige jsonbody: { "checkDate": "2023-11-16", "text": "diver_ua", "exactTextMatch": false, "matchDatabeheerder": null, "textmatchers": [ "SERIENUMMER", "REFERENTIE", "NAAM"], "matchers": [],    "instrumentTypeCode": null}
    • vb. minimale jsonbody zoeken op text: { "text": "diver_ua", "textmatchers": [ "SERIENUMMER", "REFERENTIE", "NAAM"]}
    • vb. minimale jsonbody zoeken op koppelingen: { "matchers": [ "NIET_GEKOPPELDE_INSTRUMENTEN" ], "textmatchers": [ "NAAM"]} 
    • vb. minimale jsonbody zoeken op instrumenttype: { "instrumentTypeCode": "DIV"} (of { "instrumentTypeCode": "DIV", "textmatchers": []})
  • /hfmetingen/instrumenten/
  • /hfmetingen/instrumenten/{idOrPermkey}/sensoren
    • GET → lijst opvragen van sensoren bij één instrument
  • /dovinstrumentserver/appinstrument/instrumenten/{idOrPermkey}/sensordata  
    • GET → lijst opvragen van sensoren bij één instrument, met ook info over parameters, aantal datapunten, laatste timestamp, laatste succesvolle data-import, ...
  • /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
    • PUT /hfmetingen/instrumentlink/{linkid}?comment=Update%20link → aan passen van een link (bv. koppelnaam) 
  • GET /hfmetingen/meetreeksen/{domainObjectType}/{objectPermkey}/sensortypes → opvragen sensortypes bij een filter of bodemlocatie
  • GET /hfmetingen/meetreeksen/{domainObjectType}/{objectPermkey}/parameters/{parameterId}/meetpunten &
    GET /hfmetingen/meetreeksen/{domainObjectType}/{objectPermkey}/parameters/{parameterId}/sensortypes/{sensorIdentificatieCode}/meetpunten → opvragen van de meetreeksdata van een filter of bodemlocatie (als json, zip of csv). 
    • Het eerste endpoint is geschikt voor locaties waar het instrument enkel sensoren met verrschillende parameters heeft (bv. diver → temp en waterdiepte),
    • het tweede endpoint is geschikt voor locaties waar er per parameter meerdere sensoren kunnen zijn, en er dus gewerkt wordt met een sensoridentificatie (bv. gazondolken hebben drie temperatuursensoren, met sensoridentificatie CN_T1, CN_T2, CN_T3). Ook voor andere sensoren van hetzelfde instrument, zelfs al zijn ze uniek voor de parameter (bv. bodemvochtsensor op een gazondolk) moet dit endpoint gebruikt worden.
    • Volgende parameters kunnen worden meegegeven: startDatum, eindDatum, type (gevalideerd, niet_gevalideerd)
    • Bovenstaande requests vragen een JSON op. Alternatief kan een CSV of ZIP gedownload worden door de accept waarde te vervangen door "text/csv" of "application/zip".
  • GET /hfmetingen/meetreeksen/{FILTER_PERMKEY}/sensortypes/{SENSORTYPE_CODE}/meetpunten → onduidelijk of deze call nog werkt. 


Nuttige API-calls voor grondwater

(geen documentatie beschikbaar):

  • Filters en putten:
    • POST https://www.dov.vlaanderen.be/zoeken-ocdov/proxy-filter/filter/search?maxresults=100 → opzoeken van een filter en put op naam (opgelet: kan meerdere resultaten geven, geeft [ ] indien niets gevonden). 
      • body is: { "@class": "org.geomajas.gwt2.plugin.wfs.server.dto.query.LogicalCriterionDto", "children": [{ "@class": "org.geomajas.gwt2.plugin.wfs.server.dto.query.StringAttributeCriterionDto", "attributeName": 'GW-ID', "operation": "like", "value": SEARCHVALUE }
      • alternatieve attributen waarin gezocht kan worden: "GW-ID", 'Namen put', 'FilterPermKey', 'GrondwaterlocatiePermkey'

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

Hieronder de PRODUCTIE versie, voor OEFEN is de basisurl https://services-oefen.dov.vlaanderen.be. 

Testen van certificaat

Hieronder drie endpoints die kunnen gebruikt worden om connectie en certificaten te testen

  1. Test Chuck Norris: werkt niet met een fout certificaat, werkt wel zonder certificaat (dit kan bv. gebruikt worden om de connectie te testen)
    https://services-oefen.dov.vlaanderen.be/dovinstrumentserver/chucknorris → OEFEN
    https://services.dov.vlaanderen.be/dovinstrumentserver/chucknorris            → PRODUCTIE
    • response met correct certificaat: "Chuck Norris is the reason Waldo is hiding", 
    • response bij geen certificaat: "Chuck Norris is the reason Waldo is hiding"
    • response bij ongeldige certificaat: 403 Forbidden
  2. Test LogCounts: werkt enkel al je een geldig certificaat hebt (het moet wel een certificaat zijn dat rechten heeft op XML-imports) 
    https://services-oefen.dov.vlaanderen.be/dov-xdov-server/logs/count          → OEFEN
    https://services.dov.vlaanderen.be/dov-xdov-server/logs/count          → PRODUCTIE
    • response met correct certificaat: {"count":2392} (getal kan varieren)
    • response zonder certificaat: Access is denied
    • response bij ongeldig certificaat: 403 Forbidden
  3. Test ActorenLijst: werkt enkel al je een geldig certificaat hebt (werkt voor certificaten met rechten op hetzij instrument API hetzij XML-imports) 
    https:/services-oefen.dov.vlaanderen.be/dovkernserver/actoren/0                → OEFEN
    https://services.dov.vlaanderen.be/dovkernserver/actoren/0                         → PRODUCTIE
    • response met correct certificaat: {"id":"0","naam":"system","voornaam":null,"telnr":null,  .  .  .  .  ,"actief":true} 
    • response zonder certificaat: Access is denied
    • response bij ongeldig certificaat: 403 Forbidden

Beperkte json-bodies

In de API-documentatie staat bij elke POST-endpoint een json-body meegegeven als voorbeeld. Dit is echter zeer uitgebreid, en bevat alle attributen. In de meeste gevallen volstaat echter een beperkte set aan attributen om nieuwe instrumenten of koppelingen aan te maken. Hieronder worden enkele beknoptere voorbeelden gegeven. 

Aanmaken van een instrument

request_url = "https://services-oefen.dov.vlaanderen.be/hfmetingen/instrumenten/"

Gazondolk (voorbeeld beperkt JSON-body) 
{
            "metadata": {
                "naam": "bart_test_dolk_imdc2",
                "type": {
                    "code": "TMS"
                },
                "serienummer": "BPA1235",
                "referentie": "CN: " + "bart_test_dolk2",
                "datumInGebruik": "2020-01-01", 
                "typeNummer": {
                    "code": "TMS4"
                },
                "transmissie": {
                    "code": "MAN"
                }
            },
            "objectBeheer": {
                "status": {
                    "code": "4"
                },
                "databeheerder": {
                    "id": "8"
                }
            },
            "compensatieData": {},
            "sensorData": {
                "sensoren": [
                    {
                        "naam": "SWC",
                        "parameter": {
                            "id": 1912
                        },
                        "sensorIdentificatie": {
                            "code": "CN_SWC"
                        },
                        "meeteenheid": {
                            "code": 127
                        }
                    },
                    {
                        "naam": "T1",
                        "parameter": {
                            "id": 1911
                        },
                        "sensorIdentificatie": {
                            "code": "CN_T1"
                        },
                        "meeteenheid": {
                            "code": 3
                        }
                    },
                    {
                        "naam": "T2",
                        "parameter": {
                            "id": 1911
                        },
                        "sensorIdentificatie": {
                            "code": "CN_T2"
                        },
                        "meeteenheid": {
                            "code": 3
                        }
                    },
                    {
                        "naam": "T3",
                        "parameter": {
                            "id": 1911
                        },
                        "sensorIdentificatie": {
                            "code": "CN_T3"
                        },
                        "meeteenheid": {
                            "code": 3
                        }
                    }
                ]
            }
        }


Diver (voorbeeld beperkt JSON-body ) 
{
    "metadata": {
        "naam": "bart_test_diver_imdc1",
        "type": {
            "code": "DIV",
        },
        "serienummer": "BPA_1234",
        "referentie": "",
        "datumInGebruik": "2022-05-02",
        "typeNummer": {
            "code": "11110304",
        },
        "transmissie": {
            "code": "GPRS",
        }
    },
    "objectBeheer": {
        "status": {
            "code": "4",
        },
        "databeheerder": {
            "id": "10",
        }
    },
    "sensorData": {
        "sensoren": [{
            "naam": "Waterpeil",
            "parameter": {
                "id": "1914",
            },
            "meeteenheid": {
                "code": "200",
            }
        }]
    },
    "compensatieData": {}
}

Tips:

Gekende foutmeldingen:

  • Dubbele referentie -> Referentie moet uniek zijn binnen organisatie",{"msg":"Er bestaat reeds een instrument met serienummer \
  • referentie leeg of "" -> GEEN PROBLEEM, dit lukt
  • Dubbele serienummer -> Er bestaat reeds een instrument met serienummer \"BPA1235\"
  • Dubbele naam -> GEEN PROBLEEM, dit lukt.
  • databheerder = 8 ipv 10 -> Access is denied
  • datum in gebruik: kan zowel met als zonder uur zijn
  • datum in gebruik: indien geen geldige datum -> JSON parse error: Cannot deserialize value of type [null] from String "": not a valid representation (error: Unparseable date
  • fout instrumenttype -> Instrumenttype met code "TMS2" kon niet gevonden worden bij DOV
  • fout typenummer -> Typenummer met code "TMS43" kon niet gevonden worden bij DOV.
  • fout transmissie ->Transmissie met code "MAN3" kon niet gevonden worden bij DOV.

Koppelen van een Instrument

request_url = "https://services-oefen.dov.vlaanderen.be/hfmetingen/instrumentlink/"

Gazondolk koppelen aan Bodemlocatie (voorbeeld beperkt JSON-body) 
{
            "objectType": "BODEMLOCATIE",
            "instrument": {
                "permKey": INSTRUMENT_PERMKEY
            },
            "bodemObjectLinkMetadataDto": {
                "bodemobject": {
                    "permKey": BODEMLOCATIE_PERMKEY
                },
                "startDiepte" : -10,
                "eindDiepte": 13,
                "koppelnaam": "barttest-01",
                "van": "01-11-2022 08:00:00",
                "tot": null,
                "status" : {
                    "code": "4"
                }
            },
            "partner": "8",
            "securityStatus": "PUBLIEK"
        }


Diver koppelen aan Filter (voorbeeld beperkt JSON-body) 
 {
            "objectType": "FILTER",
            "instrument": {
                "permKey": INSTRUMENT_PERMKEY
            },
            "filterObjectLinkMetadataDto": {
                "filter": {
                    "permKey": FILTER_PERMKEY
                },
                "koppelnaam": "barttest-01",
                "van": "01-06-2023 08:00:00",
                "tot": null,
                "status" : {
                    "code": "4"
                },
                # "ophangLengte" : 6.0,
                # "referentie" : {
                #     "code" : "1"
                # },
            },
            "partner": "10",
            "securityStatus": "PUBLIEK"
        }

Tips:

  • Opgelet: ophanglengte en referentie kunnen weggelaten worden (daarom staan ze in comment in voorbeeld hierboven). Als je ze wel wilt toevoegen, moeten ze allebei samen aanwezig zijn. 
  • indien je een koppeling wil updaten (bv. wijzigen van koppeldatum), dan gebruik je PUT. In de json voeg je dan het volgende attribuut toe: 'filterObjectLinkMetadataDto>id' of 'bodemObjectLinkMetadataDto>id' . id is de linkid.  

Gekende foutmeldingen:

  • overlappend interval met een bestaande koppeling -> foutmelding "Het interval van de koppeling voor deze bodemlocatie mag niet overlappen met een interval van een andere koppeling met deze bodemlocatie"
  • attribuut 'referentie' niet aanwezig, maar attribuut 'ophanglengte' wel -> foutmelding "Referentie moet ingevuld zijn indien ophanglengte is ingevuld."
  • attribuut 'ophanglengte' niet aanwezig, maar attribuut 'referentie' wel -> foutmelding "ophanglengte moet ingevuld zijn indien referentie is ingevuld"
  • attribuut 'koppelnaam' niet aanwezig -> foutmelding "Het veld mag niet leeg zijn."
  • Linkid ontbreekt in de URL bij een PUT-operatie (en dus eigenlijk een ander endpoint) → "method PUT is not allowed"
  • attribuut 'filterObjectLinkMetadataDto>id' niet aanwezig bij een PUT-operatie → foutmelding: "null"
  • ongekende linkid bij PUT- of DELETE-operatie → foutmelding "Unable to find be.vlaanderen.dov.instrument.entity.objectlink.InstrumentObjectLink with id 9000"

Opladen van tijdreeksdata

request-url: https://services-oefen.dov.vlaanderen.be/hfmetingen/instrumenten/{idOrPermkey}/sensoren/{sensorIdOrPermkey}/meetpunten

Upload van 1 datapunt (via json, synchrone verwerking), meerdere datapunten (via json, asynchrone verwerking) of een csv-bestand (asynchrone verwerking). 

Over het formaat van het csv-bestand:

  • Komma-gescheiden waarden, geen hoofdingrij
  • drie velden: 'tijd', 'waarde', 'gevalideerd'
    • Tijd: formaat = yyy-MM-ddTHH:mm:ss.SSSXXX
    • Waarde: getal
    • Gevalideerd: 0 (niet gevalideerd) of 1 (gevalideerd)

Voorbeeld:

2018-08-29T23:59:00.000+01:00,20.13,1
2018-08-31T14:26:00.000+01:00,20.35,1
2018-09-03T08:13:00.000+01:00,20.27,1


  • Geen labels