Inleiding

Hieronder wordt een overzicht gegeven van de API-endpoints/calls om sensordata m.b.t. grondwater/bodem toe te voegen aan DOV.

De meest recent technische handleiding is te vinden op dov.vlaanderen.be/portaal/api/instrument/api-guide.html. Sommige endpoints hieronder beschreven zijn nog niet gedocumenteerd in de handleiding, maar kunnen wel nuttig zijn bij het uitwerken van scripts.

De endpoints zijn beschreven voor de productie omgeving.  Vervang 'services.dov.vlaanderen.be' door 'services-oefen.dov.vlaanderen.be' voor de oefen omgeving. Deze omgeving kan gebruikt worden om te testen zonder de data van de productie omgeving te wijzigen.

Een volledige url kan gevormd worden door de basis url en endpoint samen te voegen. Bijvoorbeeld basis url = 'https://services.dov.vlaanderen.be/' + endpoint = 'dovinstrumentserver/chucknorris' geeft 'https://services.dov.vlaanderen.be/dovinstrumentserver/chucknorris'.

Certificaat testen

Drie calls voor het testen van de connectie en het certificaat.

  • GET /dovinstrumentserver/chucknorris → testen connectie
    • Werkt niet met een fout certificaat, wel zonder certificaat.
      • response met correct certificaat: "Chuck Norris is the reason Waldo is hiding"
      • response zonder certificaat: "Chuck Norris is the reason Waldo is hiding"
      • response met ongeldige certificaat: 403 Forbidden
  • GET /dov-xdov-server/logs/count → testen certificaat
    • Werkt alleen met geldig certificaat (met rechten op XML-imports)
      • response met correct certificaat: {"count":2392} (getal kan variëren)
      • response zonder certificaat: Access is denied
      • response met ongeldig certificaat: 403 Forbidden
  • GET /dovkernserver/actoren/0 testen certificaat
    • Werkt alleen met geldig certificaat (met rechten op XML-imports) 
      • response met correct certificaat: {"id":"0","naam":"system","voornaam":null,"telnr":null,  .  .  .  .  ,"actief":true} 
      • response zonder certificaat: Access is denied
      • response met ongeldig certificaat: 403 Forbidden

API-calls instrument

  • POST /dovinstrumentserver/appinstrument/search/instrumenten/ → oplijsten alle bekende instrumenten
    • In de json-body kunnen volgende parameters worden meegegeven:
      • instrumentTypeCode (optioneel): filter op instrumentTypeCode, bijvoorbeeld {"instrumentTypeCode": "TMS"} of {"instrumentTypeCode": "DIV"}.
      • text (optioneel): filter op instrumenten waarin deze tekst voorkomt, bijvoorbeeld {"text": "diver_UA_"}
      • textmatchers (optioneel): specifieert de velden waarin text zoekt, bijvoorbeeld. ["SERIENUMMER", "NAAM" ] (hoofdletters nodig).
        • 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.
      • exactTextMatch (optioneel)True/False, bij True zoekt naar een exacte match (default = False). 
      • matchers (optioneel)geeft labels waarmee de instrumenten worden gefilterd, bijvoorbeeld ["GEKOPPELDE_INSTRUMENTEN", "ACTIEVE_INSTRUMENTEN", "NIET_ACTIEVE_INSTRUMENTEN", "NIET_GEKOPPELDE_INSTRUMENTEN" ] (default= []).
        • Opgelet: dit attribuut moet samen gebruikt worden met textmatchers (met minstens 1 listelement) of met instrumentTypeCode. Anders wordt de volledige lijst gegeven. 
    • Voorbeelden van json-body
      • volledige jsonbody: { "checkDate": "2023-11-16", "text": "diver_ua", "exactTextMatch": false, "matchDatabeheerder": null, "textmatchers": [ "SERIENUMMER", "REFERENTIE", "NAAM"], "matchers": [], "instrumentTypeCode": null}
      • zoek op text: { "text": "diver_ua", "textmatchers": [ "SERIENUMMER", "REFERENTIE", "NAAM"]}
      • zoek op koppelingen: { "matchers": [ "NIET_GEKOPPELDE_INSTRUMENTEN" ], "textmatchers": [ "NAAM"]} 
      • zoek op instrumenttype: { "instrumentTypeCode": "DIV"} (of { "instrumentTypeCode": "DIV", "textmatchers": []})
  • /hfmetingen/instrumenten/
  • GET /hfmetingen/instrumenten/{idOrPermkey}/sensoren → oplijsten van sensoren bij één instrument
  • GET /dovinstrumentserver/appinstrument/instrumenten/{idOrPermkey}/sensordata oplijsten van sensoren van één instrument
    • inclusief 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)
      • voorbeeld jsonbody voor het opladen van 1 datapunt: 
        • [{"tijd": "2022-09-12T11:11:11.000Z",
             "waarde": 11.0,
             "status": "GEVALIDEERD"}]
        • Let op de 3 cijfers na de komma voor seconden zijn nodig.
    • DELETE → verwijderen van datapunten
      • meegeven van startDatum als query parameter is verplicht.
      • Bijvoorbeeld: DELETE /hfmetingen/instrumenten/{idOrPermkey}/sensoren/{sensorIdOrPermkey}/meetpunten?startDatum=2022-09-07T03%3A00%3A00.000%2B02%3A00'
  • GET /hfmetingen/importlog/{id} → geeft de status van een import job
  • /hfmetingen/instrumentlink/
    • GET /dovinstrumentserver/appinstrument/instrumenten/{id}/links/ → lijst opvragen van links bij een instrument.
      • Opgelet: werkt enkel met id, niet met permkey.
    • POST /hfmetingen/instrumentlink/ → instrument linken aan filter of bodemlocatie
    • 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".

API-calls voor grondwater

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

API-calls voor bodem

  • 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

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