Gegevens opvragen via de SOAP API's

Om de SOAP API's 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 API voor de mogelijkheden.

Wil je gegevens opvragen van verschillende registratieobjecten? Dan moet je per registratieobject aansluiten op de SOAP API's. De modellen zijn nog niet op te vragen via een SOAP API.

Stap 1: aansluiten op SOAP API's

Om gebruik te kunnen maken van de SOAP API moet jouw organisatie aangemeld zijn bij de BRO als bronhouder, dataleverancier of data-afnemer en heb je een PKIoverheid services servercertificaat nodig. Dit certificaat is te verkrijgen bij diverse leveranciers.

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 API voor dit registratieobject gerealiseerd.

Stap 2: de inhoud van een BRO-verzoek maken

Voor het opvragen van gegevens via de SOAP API 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 het registratieobject geotechnisch sondeeronderzoek (CPT) is er in plaats van een berichtencatalogus een koppelvlakbeschrijving uitgifte en een uitgiftehandboek.