Getting Started

De ‘BRP bewoning’ Web API is gespecificeerd in OpenAPI specifications (OAS).

Wil je de API gebruiken? Dit kun je doen:

  1. Bekijk de functionaliteit en specificaties
  2. Implementeer de API
  3. Probeer en test de API

Functionaliteit en specificaties

Met de bewoning API kun je:

  • raadplegen welke personen op het opgegeven adres (adresseerbaar object) wonen of hebben gewoond
  • raadplegen welke medebewoners de opgegeven persoon heeft (gehad)
  • indicatie raadplegen voor het verloop op het adres in de vorm van het aantal inverhuizingen en uitverhuizingen en het gemiddeld aantal bewoners

De bewoning API kun je op drie manieren gebruiken:

  1. Met een peildatum. Je krijgt dan de (mede)bewoners op de opgegeven datum.
  2. Met een periode (datumVan en datumTotEnMet). Je krijgt dan de (mede)bewoners of het verloop in de opgegeven periode.
  3. Zonder peildatum of periode. Je krijgt dan alle (mede)bewoners of het totale verloop zoals bekend in de registratie.

Als je wilt kun je de gegevens van de (mede)bewoners direct meeladen met gebruik van de expand parameter.

Je kunt een visuele weergave van de specificatie bekijken met Swagger UI of Redoc.

Je kunt de functionele documentatie vinden in de features.

Implementeer de API

Je kunt code genereren op basis van de genereervariant van de specificaties.

Probeer en test de API

Wil je de ‘BRP bewoning’ Web API proberen en testen? Kijk op: https://www.haalcentraal.nl/haalcentraal/api/bewoning

Om de web api te gebruiken heb je een apikey nodig. Deze voeg je aan een request toe als header “X-API-KEY”. Een API-key vraag je aan bij de product owner cathy.dingemanse@denhaag.nl.

De Haal Centraal probeeromgeving gebruikt GBA-V op basis van de gemeentelijke autorisatie “Algemene gemeentetaken” voor buitengemeentelijke personen. Dit betekent dat de GBA-V niet alle gegevens teruggeeft die in de response zijn gedefinieerd. In de API mapping kun je zien welke gegevens wel of niet onder deze autorisatie vallen.

Je kan de Haal Centraal probeeromgeving niet gebruiken vanuit de browser, dus ook niet vanuit de browserversie van Postman. Gebruik dus de desktopversie van een testtool (zoals Postman) om berichten te sturen.

Importeer de specificaties in Postman

De werking van de API is het makkelijkst te testen met behulp van Postman. We hebben al een Postman collection voor je klaargezet. Deze kun je importeren in Postman.

Configureer de url en api key

  1. Klik bij “BRP bewoning” op de drie bolletjes.
  2. Klik vervolgens op Edit
  3. Selecteer tabblad “Authorization”
  4. Kies TYPE “API Key”
  5. Vul in Key: “x-api-key”, Value: de API key die je van Cathy hebt ontvangen, Add to: “Header”
  6. Selecteer tabblad “Variables”
  7. Vul bij baseUrl INITIAL VALUE en bij CURRENT VALUE: https://www.haalcentraal.nl/haalcentraal/api/bewoning
  8. Klik op de knop Update

Testpersonen

Deze tabel bevat de burgerservicenummers van testpersonen voor specifieke situaties waarmee de ‘BRP bewoning’ Web API kan worden getest.

burgerservicenummer situatie
999993872 meerdere medebewoners
999992740 medebewoners met familierelatie
999991292 medebewoners niet gerelateerd

De API gebruikt de GBA-V proefomgeving. Alle testpersonen die daarin voorkomen kun je ook in de API gebruiken. De volledige set testpersonen kan worden gedownload bij de RvIG. Een vertaling van GBA-V (LO GBA) attributen naar BRP API properties staat beschreven in de BRP-LO GBA mapping.