Gegevens opvragen via de SOAP webservices
Jij kunt volledig geautomatiseerd BRO-gegevens opvragen via een SOAP webservice. Lees eerst de algemene beschrijving van de SOAP webservices voordat je verder leest. Hieronder beschrijven we de stappen die je moet doorlopen om aan te sluiten op deze SOAP webservice.
Om de SOAP webservice te gebruiken heeft jouw organisatie een PKI-certificaat nodig. Wil je BRO-gegevens opvragen zonder PKI-certificaat? Bekijk dan de algemene omschrijving van de SOAP webservices voor de mogelijkheden.
Wil je gegevens opvragen van verschillende registratieobjecten? Dan moet je per registratieobject aansluiten op de SOAP webservices. De modellen zijn nog niet op te vragen via een SOAP webservice.
Stap 1: aansluiten op SOAP webservices
Als jouw organisatie als bronhouder of dataleverancier aangemeld is bij de BRO, dan kun je met een PKIoverheid certificaat gebruikmaken van de SOAP webservice. Is jouw organisatie geen bronhouder of dataleverancier, meld je dan aan voor de SOAP webservice. Ook dan heb je een PKIoverheid certificaat nodig.
Als jouw organisatie nog niet beschikt over een PKIoverheid-certificaat, dan kun je eerst aansluiten op de demo-omgeving. Je kunt hiervoor een testcertificaat opvragen bij de BRO Servicedesk. Met dat certificaat en deze uitleg over de installatie van dat certificaat (daar vind je ook de endpoints), kun je aansluiten op de demo-omgeving van de BRO. Bij die uitleg staat ook hoe je een simpel verzoek (request) kunt aanmaken.
Om daadwerkelijk BRO-gegevens op te kunnen vragen, moet je aansluiten op de productieomgeving. In de productieomgeving is het niet mogelijk om gebruik te maken van het testcertificaat. Je hebt dan een geldig PKIoverheid-certificaat nodig om jezelf te authentiseren. De overgang van de demo-omgeving naar de productieomgeving is vervolgens niet meer dan het aanpassen van het endpoint voor de productieomgeving (zie uitleg over opbouw url endpoint) en het vervangen van het testcertificaat door jouw eigen geldig certificaat. Als het endpoint is aangepast, is de aansluiting op de SOAP webservice voor dit registratieobject gerealiseerd.
Stap 2: de inhoud van een BRO-verzoek maken
Voor het opvragen van gegevens via de SOAP webservice volg je een getrapte aanpak. Binnen de gegeven criteria, bijvoorbeeld een zoekgebied, vraag je met een BRO-verzoek eerst de zogenaamde kengegevens op (ook wel kenset genoemd). Dat zijn de karakteristieken van een registratieobject. Vervolgens kun je op basis van de gewenste karakteristieken alle gegevens van de bijbehorende BRO-ID’s opvragen.
Deze getrapte aanpak is niet van toepassing bij de registratieobjecten grondwatermonitoringnet, grondwaterstandonderzoek en grondwatersamenstellingsonderzoek. Dit zijn namelijk registratieobjecten zonder locatie; de locatie wordt bepaald door de grondwatermonitoringput waaraan deze gegevens zijn gekoppeld. Met een BRO-verzoek vraag je in één keer een volledig onderzoek op. Door de grootte van de uitgifte XML dien je bij grondwaterstandonderzoek ook een periode te specificeren.
In de BRO Productomgeving is per registratieobject alle documentatie beschikbaar om de inhoud van een BRO-verzoek te maken. Je vindt er voorbeelden van BRO-verzoeken die voldoen aan de technische XML berichtenschema’s (XSD’s). Bij deze XSD’s staan zowel de generieke als de specifieke BRO schema’s, bijvoorbeeld ‘brocommon’ en ‘bhrgtcommon’. Daarbij staat 'ds' voor dispatch service en 'is' voor innameservice. Voor het opvragen van gegevens heb je de ds-schema's nodig.
Ook vind je in de BRO Productomgeving per registratieobject een technische berichtencatalogus* voor de uitgiftewebservice met daarin een uitgebreide beschrijving om de inhoud van een BRO-verzoek verder te bepalen. In de berichtencatalogus staan ook waardenlijsten (codelijsten en/of referentielijsten) en een praktische vertaallijst. Meer informatie over de registratieobjecten is te vinden in de gegevenscatalogus. Voor een aantal registratieobjecten is als aanvulling op de gegevenscatalogus ook één of meerdere werkafspraken van toepassing.
*Voor de registratieobjecten geotechnisch sondeeronderzoek (CPT) en grondwatermonitoringput (GMW) is er in plaats van een berichtencatalogus een koppelvlakbeschrijving uitgifte en een uitgiftehandboek.