Adressenregister | skryvdocs

Inleiding

Via de adressenregister-connector verifieer je of een adres in Vlaanderen officieel bestaat, en vraag je bijkomende gegevens op over een specifiek adres, gebouw of gebouwunit. De connector spreekt de Adressenregister-API aan, onderdeel van de Basisregisters Vlaanderen van Digitaal Vlaanderen.

Use case

De adressenregister-connector wordt gebruikt om een adres dat een burger of medewerker invult, te toetsen tegen de officiële adresgegevens van Vlaanderen, en om bijkomende informatie over dat adres op te halen voor verdere verwerking in het dossier.

Typisch verloop binnen een Skryv-toepassing:

Een burger of medewerker geeft een adres in, bijvoorbeeld via een aanvraagformulier.
De workflow verifieert dit adres via matchAddressV2 (minstens de straatnaam, en minstens één van gemeentenaam/postcode, zijn hiervoor verplicht).
Levert dit een match op, dan gebruik je het teruggegeven objectId van het adres of gebouw om bijkomende gegevens op te vragen: detailinformatie over een gebouw (getBuildingV2) of gebouwunit (getBuildingUnitV2), of de lijst van gebouwunits op dat adres (listBuildingUnitsV2).
Levert de verificatie geen match op (een lege resultatenlijst), dan toont de workflow een foutmelding aan de gebruiker en vraagt om het adres te corrigeren.

Setup

Onboardingsprocedure adressenregister

Hoewel je de API ook anoniem kan gebruiken, is het aangeraden om de onboardingsprocedure te doorlopen en een API key aan te vragen. Dit zorgt er ook voor dat je een groter aantal requests per seconde kan sturen. Bezoek deze pagina als startpunt om de API-key aan te vragen.

Dependency toevoegen aan het pom.xml bestand

Om de connector te kunnen gebruiken, voeg je deze eerst als maven dependency toe aan het pom.xml bestand van je applicatie. Deze haalt de code voor de connector op bij het maken van de build voor je app.

<dependency>
   <groupId>com.skryv.connectors</groupId>
   <artifactId>adressenregister</artifactId>
   <version>${skryv.version}</version>
</dependency>

Applicatie instellingen

Volgende applicatie eigenschappen kunnen ingesteld worden bij de technische setup van de Adressenregister-connector.

Eigenschap	Default	Beschrijving
AdressenregisterConnector
`skryv.connectors.adressenregister.service.url`	`https://api.basisregisters.vlaanderen.be`	Deze parameter bevat de URL van de service waarmee de applicatie verbinding maakt met het Adressenregister.
`skryv.connectors.adressenregister.api-key`	-	Deze parameter bevat de API-sleutel die wordt gebruikt voor authenticatie bij de Adressenregister-service. De API-sleutel wordt meegestuurd met elk verzoek om toegang te krijgen tot de service en is vereist om de identiteit van de applicatie te verifiëren.

Resilience4j

Het adressenregister hanteert een maximum van 50 requests per seconde. Indien je dit debiet overschrijdt, dan krijg je een errorcode 429 Too Many Requests terug. Om dit te voorkomen, maken we gebruik van resilience4j en stellen we een maximale rate limit in.

Default instelling voor de adressenregister connector.

resilience4j.ratelimiter.instances.adressenregister.limit-for-period=1
resilience4j.ratelimiter.instances.adressenregister.limit-refresh-period=5s
resilience4j.ratelimiter.instances.adressenregister.timeout-duration=10s
resilience4j.retry.instances.adressenregister.max-attempts=3
resilience4j.retry.instances.adressenregister.wait-duration=1000

Externe documentatie

Klik hier voor de documentatie langs de kant van Digitaal Vlaanderen.

Services en functies

Overzicht

Functie	Retourtype	Info
matchAddressV2	`AddressMatchOsloCollection`	Nagaan of een adres bestaat in Vlaanderen en de officiële gegevens ervan opvragen.
getBuildingV2	`BuildingOsloResponse`	Detailgegevens van een gebouw opvragen op basis van een `objectId`.
getBuildingUnitV2	`BuildingUnitOsloResponse`	Detailgegevens van een gebouwunit opvragen op basis van een `objectId`.
listBuildingUnitsV2	`BuildingUnitListOsloResponse`	Lijst van gebouwunits opvragen, gefilterd op adres (`addressObjectId`) en/of gebouw (`buildingObjectId`).

Elke functie hieronder is, naast de workflow expressie, ook rechtstreeks aanroepbaar vanuit Java-code door AdressenregisterConnector (bean adressenregister) te injecteren in je klasse.

Java

@RequiredArgsConstructor
public class MyOwnService {
    private final AdressenregisterConnector adressenregister;
}

matchAddressV2

Via deze functie kan je checken of een opgegeven adres inderdaad bestaat en in Vlaanderen ligt. Je krijgt een object terug met daarin alle informatie over het adres.

Workflow expressie

${adressenregister.matchAddressV2(String municipalityName, String postalCode, String street, String houseNumber, String busNumber)}

Java-code

AddressMatchOsloCollection response = adressenregister.matchAddressV2(
        municipalityName, postalCode, street, houseNumber, busNumber);

Input

Inputparameters	Data type	Verplicht	Voorbeeld	Uitleg
`municipalityName`	String	Nee. Samen met `postalCode` moet minstens één van beide ingevuld zijn	‘Antwerpen’	Gemeentenaam van het adres.
`postalCode`	String	Nee. Samen met `municipalityName` moet minstens één van beide ingevuld zijn	‘2000’	Postcode van het adres.
`street`	String	Ja	‘Markt’	Straatnaam van het adres.
`houseNumber`	String	Nee	'1'	Huisnummer van het adres.
`busNumber`	String	Nee	'1'	Busnummer van het adres.

De connector geeft enkel deze vijf parameters door aan de externe API. De API zelf ondersteunt ook een filter op niscode en status, maar die worden door de Adressenregister-connector niet doorgegeven.

Output

Je krijgt een object AddressMatchOsloCollection terug met alle officiële gegevens voor het opgegeven adres: id van het adres, id van de gebouwen op het adres, of die gebouwen al dan niet actief zijn, etcetera. Levert de zoekopdracht geen enkele match op, dan is dat geen foutmelding maar een geldig antwoord: je krijgt een normale 200 OK terug met een lege adresMatches-lijst.

Belangrijkste velden:

Veld	Uitleg
`adresMatches[]`	Lijst van gevonden adressen (kan leeg zijn, geen match — geen fout). Elke match bevat:
`identificator.objectId`	Het unieke ID van het adres — nodig voor `listBuildingUnitsV2` (`addressObjectId`).
`gemeente.gemeentenaam.geografischeNaam.spelling`	De gemeentenaam, bv. `"Gent"`.
`straatnaam.objectId`	Het ID van de straatnaam.
`huisnummer`	Het huisnummer.
`volledigAdres.geografischeNaam.spelling`	Het volledige adres in leesbare vorm, bv. `"Aalbessenlaan 14, 9032 Gent"`.
`adresPositie.geometrie`	GML-positie van het adres.
`adresStatus`	Status van het adres, bv. `inGebruik`.
`officieelToegekend`	Of het huisnummer officieel toegekend is (`true`/`false`).
`score`	Matchscore (0–100). Geeft aan hoe goed de opgegeven zoekterm overeenkomt met dit adres.
`links[]`	HATEOAS-links naar gekoppelde `percelen` en `gebouweenheden` — dit zijn de links die `getMatchAddressLinksBuildingUnits` gebruikt (de nog niet gedocumenteerde vijfde functie).
`warnings[]`	Optionele waarschuwingen, bv. een onbekende postcode die genegeerd werd — geen fout, wel het melden waard.

Voorbeeld:

JSON

{
  "adresMatches": [
    {
      "identificator": { "objectId": "36416228" },
      "gemeente": {
        "objectId": "44021",
        "gemeentenaam": { "geografischeNaam": { "spelling": "Gent" } }
      },
      "straatnaam": {
        "objectId": "69499",
        "straatnaam": { "geografischeNaam": { "spelling": "Aalbessenlaan" } }
      },
      "huisnummer": "14",
      "volledigAdres": { "geografischeNaam": { "spelling": "Aalbessenlaan 14, 9032 Gent" } },
      "adresStatus": "inGebruik",
      "officieelToegekend": false,
      "score": 89.3,
      "links": [
        { "href": "https://api.basisregisters.vlaanderen.be/v2/percelen?adresobjectid=36416228", "rel": "percelen", "type": "GET" },
        { "href": "https://api.basisregisters.vlaanderen.be/v2/gebouweenheden?adresobjectid=36416228", "rel": "gebouweenheden", "type": "GET" }
      ]
    }
  ],
  "warnings": [
    { "code": "4", "message": "Onbekende 'Postcode'." }
  ]
}

Error-handling

Statuscode	Betekenis
`400`	Ongeldige of onvolledige aanvraag (bv. `street` ontbreekt, of geen van `municipalityName`/`postalCode` ingevuld).
`403`	Onvoldoende rechten (bv. ongeldige of ontbrekende API key voor een actie die dat vereist).
`429`	Rate limit overschreden (zie Resilience4j hierboven).
`500`	Interne fout bij de externe dienst.

Geen van deze statuscodes wordt in de connector zelf afgevangen. Een foutrespons resulteert in een onafgevangen HTTP-exceptie, en dus een Camunda-incident, geen BpmnError.

getBuildingV2

Via deze functie verkrijg je een object met alle informatie over een specifiek gebouw.

Workflow expressie

${adressenregister.getBuildingV2(String objectId)}

Java-code

BuildingOsloResponse response = adressenregister.getBuildingV2(objectId);

Input

Inputparameters	Data type	Verplicht	Voorbeeld	Uitleg
`objectId`	String	Ja	‘6’	Unieke Id van het gebouw. Krijg je terug uit `matchAddressV2`.

Output

Je krijgt een object BuildingOsloResponse terug met alle informatie over een specifiek gebouw.

Belangrijkste velden:

Veld	Uitleg
`identificator.objectId`	Het unieke ID van het gebouw (dezelfde waarde die je als `objectId` gebruikt).
`gebouwPolygoon.geometrie`	De vorm van het gebouw als GML-polygoon (coördinaten in Lambert 72).
`gebouwPolygoon.geometrieMethode`	Hoe die vorm bepaald is, bv. `ingemetenGRB`.
`gebouwStatus`	Status van het gebouw, bv. `gerealiseerd`.
`gebouweenheden[]`	Lijst van gekoppelde gebouwunits, elk met eigen `objectId`, `status` en een `detail`-link (dit zijn precies de `objectId`'s die je nodig hebt voor `getBuildingUnitV2`).
`percelen[]`	Lijst van percelen waarop het gebouw staat, elk met `objectId` en een `detail`-link.

Voorbeeld:

JSON

{
  "identificator": {
    "objectId": "6",
    "versieId": "2026-08-18T13:02:50+02:00"
  },
  "gebouwPolygoon": {
    "geometrie": {
      "type": "Polygon",
      "gml": "<gml:Polygon ...>...</gml:Polygon>"
    },
    "geometrieMethode": "ingemetenGRB"
  },
  "gebouwStatus": "gerealiseerd",
  "gebouweenheden": [
    { "objectId": "1", "status": "gerealiseerd", "detail": "https://api.basisregisters.vlaanderen.be/v2/gebouweenheden/1" },
    { "objectId": "2", "status": "gerealiseerd", "detail": "https://api.basisregisters.vlaanderen.be/v2/gebouweenheden/2" }
  ],
  "percelen": [
    { "objectId": "11001B0008-00G002", "detail": "https://api.basisregisters.vlaanderen.be/v2/percelen/11001B0008-00G002" },
    { "objectId": "11001B0008-00G003", "detail": "https://api.basisregisters.vlaanderen.be/v2/percelen/11001B0008-00G003" }
  ]
}

Error-handling

Statuscode	Betekenis
`400`	Ongeldige aanvraag.
`403`	Onvoldoende rechten.
`404`	Het gebouw kan niet gevonden worden.
`410`	Het gebouw is verwijderd.
`429`	Rate limit overschreden.
`500`	Interne fout bij de externe dienst.

Geen van deze statuscodes wordt in de connector zelf afgevangen. Een foutrespons resulteert in een onafgevangen HTTP-exceptie, en dus een Camunda-incident, geen BpmnError.

getBuildingUnitV2

Via deze functie verkrijg je een object met alle informatie over een specifieke gebouwunit.

Workflow expressie

${adressenregister.getBuildingUnitV2(String objectId)}

Java-code

BuildingUnitOsloResponse response = adressenregister.getBuildingUnitV2(objectId);

Input

Inputparameters	Data type	Verplicht	Voorbeeld	Uitleg
`objectId`	String	Ja	-	Unieke Id van de gebouwenunit. Krijg je terug uit `listBuildingUnitsV2`, of uit het `gebouweenheden[]`-veld van `getBuildingV2`.

Output

Je krijgt een object BuildingUnitOsloResponse terug met alle informatie over een specifieke gebouwunit.

Belangrijkste velden:

Veld	Uitleg
`identificator.objectId`	Het unieke ID van de gebouwunit.
`gebouweenheidPositie.geometrie`	GML-positie van de gebouwunit (punt-geometrie).
`gebouweenheidStatus`	Status, bv. `gerealiseerd`.
`functie`	Functie van de gebouwunit, bv. `gemeenschappelijkDeel`.
`gebouw.objectId`	Het `objectId` van het gebouw waartoe deze unit behoort. Nodig voor `getBuildingV2`.
`adressen[]`	Lijst van gekoppelde adressen, elk met eigen `objectId` en `detail`-link. Een gebouwunit kan dus aan meerdere adressen gekoppeld zijn.
`afwijkingVastgesteld`	Of er een vastgestelde afwijking is (`true`/`false`). Betekenis niet nader gespecifieerd in de spec zelf, dus dit vermeld ik zonder verdere interpretatie.

Voorbeeld:

JSON

{
  "identificator": { "objectId": "6" },
  "gebouweenheidPositie": {
    "geometrie": { "type": "Point", "gml": "<gml:Point ...>...</gml:Point>" },
    "positieGeometrieMethode": "aangeduidDoorBeheerder"
  },
  "gebouweenheidStatus": "gerealiseerd",
  "functie": "gemeenschappelijkDeel",
  "gebouw": { "objectId": "1", "detail": "https://api.basisregisters.vlaanderen.be/v2/gebouwen/1" },
  "adressen": [
    { "objectId": "1", "detail": "https://api.basisregisters.vlaanderen.be/v2/adressen/1" },
    { "objectId": "10", "detail": "https://api.basisregisters.vlaanderen.be/v2/adressen/10" },
    { "objectId": "7", "detail": "https://api.basisregisters.vlaanderen.be/v2/adressen/7" }
  ],
  "afwijkingVastgesteld": false
}

Error-handling

Statuscode	Betekenis
`400`	Ongeldige aanvraag.
`403`	Onvoldoende rechten.
`404`	De gebouwunit kan niet gevonden worden.
`410`	De gebouwunit is verwijderd.
`429`	Rate limit overschreden.
`500`	Interne fout bij de externe dienst.

Geen van deze statuscodes wordt in de connector zelf afgevangen. Een foutrespons resulteert in een onafgevangen HTTP-exceptie, en dus een Camunda-incident, geen BpmnError.

listBuildingUnitsV2

Via deze functie krijg je een lijst van gebouwunits die gelinkt zijn aan een specifiek adres en/of gebouw.

Workflow expressie

${adressenregister.listBuildingUnitsV2(String offset, String limit, String addressObjectId, String buildingObjectId)}

Java-code

BuildingUnitListOsloResponse response = adressenregister.listBuildingUnitsV2(
        offset, limit, addressObjectId, buildingObjectId);

Input

Inputparameters	Data type	Verplicht	Voorbeeld	Uitleg
`offset`	String	Nee (default `0`)	'0'	Nulgebaseerde index van het eerste item dat je terugkrijgt. Beperkt tot maximaal 1.000.000 — bij grotere datasets is een extra filter (`addressObjectId`/`buildingObjectId`) aangewezen.
`limit`	String	Nee	‘10’	Aantal items dat je terugkrijgt. Maximaal 500.
`addressObjectId`	String	Nee*	-	Unieke Id van het adres. Krijg je uit `matchAddressV2`.
`buildingObjectId`	String	Nee*	-	Unieke Id van het gebouw. Krijg je uit `matchAddressV2` of `getBuildingV2`.

* Beide filters zijn optioneel, maar zonder minstens één van beide krijg je een lijst van gebouwunits over heel Vlaanderen. In de praktijk geef je dus zo goed als altijd één van beide mee.

Output

Je krijgt een object listBuildingUnitsV2 terug met daarin een collectie van gebouwunits die gelinkt zijn aan een specifiek adres en/of gebouw.

Belangrijkste velden:

Veld	Uitleg
`gebouweenheden[]`	De lijst van gebouwunits. Elk item bevat enkel een beknopte samenvatting (`objectId`, `detail`-link en `gebouweenheidStatus`). Niet de volledige informatie (functie, gekoppeld gebouw, gekoppelde adressen). Voor die details roep je `getBuildingUnitV2` op met het `objectId` van het gewenste item.
`volgende`	Link naar de volgende pagina resultaten (paginering), aanwezig zolang er meer resultaten zijn dan de opgegeven `limit`.

Voorbeeld:

JSON

{
  "gebouweenheden": [
    { "identificator": { "objectId": "6" }, "detail": "https://api.basisregisters.vlaanderen.be/v2/gebouweenheden/6", "gebouweenheidStatus": "gepland" },
    { "identificator": { "objectId": "7" }, "detail": "https://api.basisregisters.vlaanderen.be/v2/gebouweenheden/7", "gebouweenheidStatus": "gerealiseerd" }
  ],
  "volgende": "https://api.basisregisters.vlaanderen.be/v2/gebouweenheden?offset=5&limit=10"
}

Error-handling

Statuscode	Betekenis
`400`	Ongeldige aanvraag (bv. `limit` groter dan 500, of `offset` groter dan 1.000.000).
`403`	Onvoldoende rechten.
`429`	Rate limit overschreden.
`500`	Interne fout bij de externe dienst.

Geen 404 voorzien voor dit endpoint — een lijst zonder resultaten is, net als bij matchAddressV2, een geldig antwoord met een lege gebouweenheden-lijst, geen fout.

Geen van deze statuscodes wordt in de connector zelf afgevangen. Een foutrespons resulteert in een onafgevangen HTTP-exceptie, en dus een Camunda-incident, geen BpmnError.