Gegevens opvragen via de SOAP webservices

U kunt volledig geautomatiseerd BRO-gegevens opvragen via een SOAP webservice. Hieronder beschrijven we twee stappen die u moet doorlopen om aan te sluiten op deze SOAP webservice.

Om de SOAP webservice te gebruiken heeft uw organisatie een PKI-certificaat nodig. Geautomatiseerd BRO-gegevens opvragen zonder PKI-certificaat kan met de zelfbeschrijvende REST-service of met één van de andere mogelijkheden. Onderaan deze pagina leest u meer daarover.

Wilt u gegevens opvragen van verschillende registratieobjecten? Dan moet u per registratieobject aansluiten op de uitgiftewebservice. De modellen zijn nog niet op te vragen via een SOAP webservice.

Stap 1: aansluiten op SOAP webservices

Om gebruik te kunnen maken van de SOAP webservice moet uw organisatie aangemeld zijn bij de BRO als bronhouder, dataleverancier of data-afnemer en u heeft een PKIoverheid services server certificaat nodig. Dit certificaat is te verkrijgen bij diverse leveranciers.

Als uw organisatie nog niet beschikt over een PKIoverheid-certificaat, dan kunt u eerst aansluiten op de demo-omgeving. U kunt hiervoor een testcertificaat opvragen bij de BRO Servicedesk. Met dat certificaat en deze uitleg over de installatie van dat certificaat (daar vindt u ook de endpoints), kunt u aansluiten op de demo-omgeving van de BRO. Bij die uitleg staat ook hoe u een simpel verzoek (request) kunt aanmaken.

Om daadwerkelijk BRO-gegevens op te kunnen vragen, moet u aansluiten op de productieomgeving. In de productieomgeving is het niet mogelijk om gebruik te maken van het testcertificaat. U heeft dan een geldig PKIoverheid-certificaat nodig om uzelf te authentiseren. De overgang van de demo-omgeving naar de productieomgeving is vervolgens niet meer dan het aanpassen van het endpoint voor de productieomgeving en het vervangen van het testcertificaat door uw 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 volgt u een getrapte aanpak. Binnen de gegeven criteria, bijvoorbeeld een zoekgebied, vraagt u met een BRO-verzoek eerst de zogenaamde kengegevens op (ook wel kenset genoemd). Dat zijn de karakteristieken van een registratieobject. Vervolgens kunt u 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 vraagt u in één keer een volledig onderzoek op. Door de grootte van de uitgifte XML dient u 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. U 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 heeft u de ds-schema's nodig.

Ook vindt u 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.

Andere mogelijkheden

  1. REST-uitgifteservice. Voor een aantal registratieobjecten is er ook een REST-uitgifteservice. Deze service is zelf-beschrijvend volgens de OPEN API standaard. De swagger-ui pagina geeft de mogelijkheid tot het proberen van de service.
  2. BRO-gegevens online bekijken. Gegevens die geregistreerd worden in de BRO zijn een dag later beschikbaar via BROloket. U kunt de gegevens op de kaart aan de hand van allerlei criteria bekijken en direct opvragen.
  3. BRO-gegevens voor uw database. Via het BROloket en PDOK (Publieke Dienstverlening op de Kaart), kunt u bestanden met BRO-gegevens opvragen. Bekijk op het BROloket en PDOK wat de formaten en mogelijkheden zijn.