diff --git a/README.md b/README.md index 0758701e..28321229 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,9 @@ -# Haal Centraal BAG Huidige Bevragingen +# BAG Individuele Bevragingen -![lint oas](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/workflows/lint-oas/badge.svg) -![generate postman collection](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/workflows/generate-postman-collection/badge.svg) + -BAG Huidige bevragingen is een Haal Centraal API voor het zoeken en raadplegen van gegevens in de basisregistratie Adressen en Gebouwen voor alle binnengemeentelijke afnemers in NL, maar ook voor waterschappen, belastingsamenwerkingen en andere overheden. -We doen ons uiterste best om de API evolvable door te ontwikkelen en geen breaking changes te introduceren. +BAG Individuele bevragingen is een API voor het zoeken en raadplegen van gegevens in de basisregistratie Adressen en Gebouwen voor alle binnengemeentelijke afnemers in NL, maar ook voor waterschappen, belastingsamenwerkingen en andere overheden. We doen ons uiterste best om de API evolvable door te ontwikkelen en geen breaking changes te introduceren. Bekijk de [release notes](https://vng-realisatie.github.io/Haal-Centraal-BAG-bevragen/releasenotes) van deze release. @@ -15,14 +14,12 @@ Bekijk de [release notes](https://vng-realisatie.github.io/Haal-Centraal-BAG-bev * Download de [technische specificaties](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/blob/master/specificatie/genereervariant/openapi.yaml) * [Vraag een API-key aan](https://formulieren.kadaster.nl/aanvraag_bag_api_huidige_bevragingen_productie) voor toegang tot de productieomgeving. - ## Bronnen -* [Productvisie Haal Centraal](https://vng-realisatie.github.io/Haal-Centraal) * [API Design Visie](https://github.com/Geonovum/KP-APIs/blob/master/overleggen/Werkgroep%20API%20design%20visie/API%20Design%20Visie.md) * [REST API Design Rules](https://docs.geostandaarden.nl/api/API-Designrules/) * [Landelijke API strategie voor de overheid](https://geonovum.github.io/KP-APIs/) -* [Stelselcatalogus](https://www.stelselcatalogus.nl/registraties/BAG/) +* [Stelselcatalogus](https://www.stelselcatalogus.nl/registraties/registratie?id=http://opendata.stelselcatalogus.nl/id/registratie/BAG) ## Contact @@ -30,14 +27,18 @@ Bekijk de [release notes](https://vng-realisatie.github.io/Haal-Centraal-BAG-bev [Maak een bug issue aan >>](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/new?assignees=&labels=bug&template=bug_report.md&title=) * Verbeteringen doorgeven [Maak een verbeter issue aan >>](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/new?assignees=&labels=enhancement&template=enhancement.md&title=) +* Storingen + [Meld een storing](https://formulieren.kadaster.nl/contact_kadaster) * Community: Wil je geïnformeerd blijven over productwijzigingen of meepraten over de API meld je dan aan bij de community.
Ga naar de community>> -* Regiseur API's: Arjen Brienen, [arjen.brienen@VNG.NL](mailto:arjen.brienen@VNG.NL) -* Designer: Johan Boer, [johan.boer@vng.nl](mailto:johan.boer@vng.nl) -* Designer: Robert Melskens, [robert.melskens@vng.nl](mailto:robert.melskens@vng.nl) +* Regiseur API's: Arjen Brienen +* Designer: Johan Boer +* Designer: Robert Melskens + +U kunt hen bereiken via [standaarden.ondersteuning@vng.nl](mailto:standaarden.ondersteuning@vng.nl) ## Licentie Copyright © VNG Realisatie 2020 -Licensed under the [EUPL](https://github.com/VNG-Realisatie/Haal-Centraal-BRK-bevragen/blob/master/LICENCE.md) +Licensed under the [EUPL](https://github.com/VNG-Realisatie/Haal-Centraal-BRK-bevragen/blob/master/LICENCE.md){:target="_blank" rel="noopener"} diff --git a/docs/_config.yml b/docs/_config.yml index f8cd521a..da413e1b 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -13,28 +13,28 @@ nav: path: / - title: Goals canvas path: /goals-canvas - - title: Haal Centraal BAG Huidige Bevragingen v. 1.5 (Deprecated) + - title: Haal Centraal BAG Huidige Bevragingen v. 1.5 (Expired) subnav: - title: Functionaliteit en specificaties - path: /getting-started + path: /getting-started-HB - title: User stories - path: /user-stories-prod + path: /user-stories-prod-HB - title: Bevragen API (swagger-ui) - path: /swagger-ui + path: /swagger-ui-HB - title: Bevragen API (redoc) - path: /redoc + path: /redoc-HB - title: Features path: /features - title: BAG Individuele Bevragingen v. 2.6 (Live) subnav: - title: Getting started - path: /getting-started-IB + path: /getting-started - title: User stories - path: /user-stories-prod-IB + path: /user-stories-prod - title: IB API (swagger-ui) - path: /swagger-ui-IB + path: /swagger-ui - title: IB API (redoc) - path: /redoc-IB + path: /redoc # - title: Features # path: https://github.com/lvbag/BAG-API/tree/master/Features # - title: Specificaties v. 1.5 (IO) diff --git a/docs/getting-started-HB.md b/docs/getting-started-HB.md new file mode 100644 index 00000000..65b0fc1f --- /dev/null +++ b/docs/getting-started-HB.md @@ -0,0 +1,106 @@ +--- +layout: page-with-side-nav +title: Functionaliteit en specificaties +--- +# Functionaliteit en specificaties - BAG Huidige Bevragingen API + +## De BAG Huidige Bevragingen API v 1.5 is expired. + +Start niet meer met de implementatie van deze API. Implementeer daarvoor in plaats de BAG Individuele Bevragingen API, we verwijzen je daarvoor naar de [Getting Started van de BAG Individuele Bevragingen v. 2.6](https://vng-realisatie.github.io/Haal-Centraal-BAG-bevragen/getting-started).

Onderstaande informatie is alleen bedoelt voor evt. resterende gebruikers van de BAG Huidige Bevragingen API. + +Je kunt de Open API Specificaties (OAS3) van de API bekijken in [Swagger-formaat](./swagger-ui-HB) of [Redoc](./redoc-HB). + +De (resolved) OAS3 is hier te downloaden: [openapi.yaml](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/blob/master/specificatie/genereervariant/openapi.yaml){:target="_blank" rel="noopener"}. + +## Beschikbare resources +De API kent de volgende resources: +- adressen: hierin zijn samenhangende en gerelateerde gegevens samengevoegd uit de nummeraanduiding, openbare ruimte en woonplaats die samen een adres vormen +- adresseerbareobjecten: dit kan een verblijfsobject, ligplaats of standplaats zijn +- nummeraanduidingen +- openbareruimten +- woonplaatsen +- panden + +Voor de verschillende resources wordt de uri samengesteld met de identificatie van het onderliggende BAG-object. Dit is een 16 cijferige, of in geval van woonplaats 4 cijferige identificatie. Voor adressen wordt de nummeraanduiding identificatie gebruikt in de uri. +De identificatie kan voorloopnullen bevatten, dus het is geen integer. + +### Zoeken van een adres +Je kan een adres zoeken met endpoint /adressen/zoek en parameter "zoek" waarin met postcode, woonplaats, straatnaam, huisnummer, huisletter en huisnummertoevoeging kan worden gezocht. Op dit moment worden alleen deze gegevens ondersteund, het is de bedoeling dat dit later volledig "fuzzy search" wordt. +Deze zoekfunctie, via endpoint /adressen/zoek levert voor elk gevonden adres een combinatie van een zoekresultaat identificatie en een omschrijving, plus een link voor het ophalen van de volledige adresgegevens. + +Deze zoekfunctie kan soms veel zoekresultaten opleveren. Daarom wordt hier [paginering](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.1.0/features/paginering.feature){:target="_blank"} toegepast. + +Op basis van de zoekresultaten kan je een gevonden adres ophalen met endpoint /adressen?zoekresultaatIdentificatie={zoekresultaatIdentificatie}, waarbij je {zoekresultaatIdentificatie} moet vervangen door een waarde voor identificatie in de zoekresultaten van /adressen/zoek. + +Bijvoorbeeld zoeken op "/adressen/zoek?zoek=nootdorp 15c dorpsstraat" levert: +``` +"_embedded" : { + "zoekresultaten" : [ + { + "omschrijving" : "Dorpsstraat 15c, 2631CR Nootdorp", + "identificatie" : "adr-89d5a4d96f09c60716c4671fdb9334b8", + "_links" : { + "adres" : { + "href" : "/adressen?zoekresultaatIdentificatie=adr-89d5a4d96f09c60716c4671fdb9334b8" + } + } + } + ] +} +``` +Het adres haal je vervolgens op met "/adressen?zoekresultaatIdentificatie=adr-89d5a4d96f09c60716c4671fdb9334b8". + +### Zoeken van adressen in een pand +Wanneer je alle adressen in een pand wilt zoeken, kan je dit doen met /adressen?pandIdentificatie={pandIdentificatie}, waarbij {pandIdentificatie} moet worden vervangen door de identificatie van het betreffende pand. Bijvoorbeeld /adressen?pandIdentificatie=0826100000000467. + +Aangezien dit veel adressen kan opleveren, wordt hier [paginering](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.1.0/features/paginering.feature){:target="_blank"} toegepast. + +Met dit endpoint kun je ook zoeken op postcode, huisnummer, huisletter en huisnummertoevoeging. +De manier waarop je met de parameter exacteMatch kunt zoeken, kun je vinden in de feature. + +### Geometrie van een woonplaats +De geometrie van een woonplaats kan zeer omvangrijk zijn. Daarom wordt de geometrie niet standaard met een woonplaats meegeleverd. Wanneer je de geometrie van de woonplaats wel wilt krijgen, dan moet je de expand parameter gebruiken. Bijvoorbeeld /woonplaatsen/2258?expand=geometrie. + +## Algemene functionaliteit +Verder zijn er nog een paar algemene functies die gelden voor alle bovenstaande aanvragen: +- Gebruik van de **fields** parameter om de response te filteren. Voor werking, zie feature [fields](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.1.0/features/fields.feature){:target="_blank"} +- Gebruik van de **expand** parameter om subresources te ontsluiten. Voor werking, zie feature [expand](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.1.0/features/expand.feature){:target="_blank"} +- Gebruik van paginering om het aantal zoekresultaten per zoekvraag te beperken. Met de **page** parameter kan een volgende pagina worden gevraagd. Met de **pageSize** parameter kan gekozen worden voor meer of minder zoekresultaten per pagina (standaard is 20, maximum is 100). Voor werking, zie feature [paginering](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.1.0/features/paginering.feature){:target="_blank"} +- Soms kan er een onderzoek lopen of een gegeven wel correct is. Er zijn dan twijfels over de juistheid van de geregistreerde waarde. De API levert deze waarde wel, maar neemt die velden dan op in **mogelijkOnjuist** met de waarde True. +- Sommige resources bevatten geometrie. De API ondersteunt op dit moment alleen het RD coördinatenstelsel (epsg:28992). Bij een aanvraag die geometrie teruglevert moet de request header **Accept-Crs** worden meegestuurd. +- Bij het zoeken van een pand op **locatie** mag de header **Content-Crs** worden meegestuurd. Wanneer je deze header weglaat wordt default coördinatenstelsel RD (epsg:28992) gebruikt wat op dit moment ook het enige het coördinatenstelsel is dat de API ondersteunt. +- Bij het zoeken naar panden en adresseerbare objecten kun je gebruik maken van bbox. +- [HAL links](https://tools.ietf.org/html/draft-kelly-json-hal-08){:target="_blank"}, die soms [templated](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.1.0/features/uri-templating.feature){:target="_blank"} worden geleverd. + +## Test de API +De werking van de API is het makkelijkst te testen met behulp van [Postman](https://www.getpostman.com/){:target="_blank"}. +De [openapi.yaml](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/blob/master/specificatie/genereervariant/openapi.yaml){:target="_blank"} kun je importeren als project, waarna de verschillende requests worden ingeladen die deze API ondersteunt. +Je kunt ook het project dat we voor je heben gemaakt gebruiken: [BAG-Bevragen-postman-collection.json](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/blob/master/test/BAG-Bevragen-postman-collection.json){:target="_blank"}. Hierin moet je alleen de base url en authenticatie (API-key) nog invullen. + + + +### Testgevallen +Onderstaande tabellen bevatten testgevallen voor specifieke situaties waarmee de werking van de API kan worden getest. + +| Resource | Testsituatie | uri | +| --------------------- | -------------------------------------------------------------------------------- | --------------------------------------- | +| adressen | Adres met diakriet in straatnaam, huisnummer, huisletter en huisnummertoevoeging | /adressen/0484200002040489 | +| adressen | Lange straatnaam | /adressen/0417200000000354 | +| adressen | Nevenadres | /adressen/0014200022197986 | +| adressen | Geconstateerd | /adressen/0014200022188962 | +| adressen | Meerdere panden op zelfde adres | /adressen/0193200000096680 | +| adresseerbareobjecten | Verblijfsobject | /adresseerbareobjecten/0599010000165822 | +| adresseerbareobjecten | Standplaats | /adresseerbareobjecten/0503030000103062 | +| adresseerbareobjecten | Ligplaats | /adresseerbareobjecten/0569020000012435 | +| adresseerbareobjecten | Meerdere gebruiksdoelen | /adresseerbareobjecten/0626019900006674 | +| adresseerbareobjecten | Met nevenadres | /adresseerbareobjecten/0014010011067299 | +| adresseerbareobjecten | Meerdere panden | /adresseerbareobjecten/0193010000096628 | +| panden | Veel adressen | /panden/0826100000000467 | +| panden | Met nevenadres | /panden/0014100010921152 | +| panden | Zonder adres | /panden/0503100000034877 | + +Tip: Je kan ook de [BAG Viewer](https://bagviewer.kadaster.nl/lvbag/bag-viewer/index.html){:target="_blank"} gebruiken om meer testgevallen te zoeken. + diff --git a/docs/getting-started-IB.md b/docs/getting-started-IB.md deleted file mode 100644 index 09e35daf..00000000 --- a/docs/getting-started-IB.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -layout: page-with-side-nav -title: Getting Started ---- -# Getting Started - -Om aan te sluiten kun je de volgende stappen doorlopen: -1. [Aanmelden om toegang te krijgen tot de acceptatie- en productieomgeving](#aanmelden) -2. [Bekijk de functionaliteit en specificaties](#functionaliteiten-en-specificaties) -3. [Implementeer de API Client](#implementeer-de-api-client) -4. [Probeer en test de API](#probeer-en-test-de-api) - -## Aanmelden - -[Vraag een API key voor de test- en productieomgeving aan.](https://formulieren.kadaster.nl/aanvraag_bag_api_individuele_bevragingen_productie) -Testen wordt bij voorkeur gedaan in de testomgeving. - -## Functionaliteiten en specificaties - -Je kunt de Open API Specificaties (OAS3) van de API bekijken in [Swagger-formaat](https://lvbag.github.io/BAG-API/Technische%20specificatie/) of [Redoc.](https://lvbag.github.io/BAG-API/Technische%20specificatie/Redoc/) -De (resolved) OAS3 is hier te downloaden: [openapi.yaml](https://api.bag.kadaster.nl/lvbag/individuelebevragingen/v2/openapi.yaml). - -### Beschikbare endpoints - -De API kent de volgende endpoints: - -• *Woonplaatsen* -• *Openbare ruimten* -• *Nummeraanduidingen* -• *Verblijfsobjecten* -• *Standplaatsen* -• *Ligplaatsen* -• *Panden* -• *Bronhouders* - - -• *Adressen*: hierin zijn samenhangende en gerelateerde gegevens samengevoegd uit de nummeraanduiding, openbare ruimte en woonplaats die samen een adres vormen. - -• *Adressen uitgebreid*: deze resource ondersteunt de mogelijkheid om met één bevraging meer informatie over het adres op te halen, zoals het bouwjaar en de gebruiksoppervlakte. - -• *Adresseerbare objecten*: dit kan een verblijfsobject, ligplaats of standplaats zijn. - -De objecten endpoints leveren één of meer (voorkomens van) object(en), met embedded resources en links. - -De endpoints *Adressen* en *Adressen uitgebreid* en *Adresseerbare objecten* zijn samengestelde (convenience) endpoints waarin de gegevens van verschillende BAG objecten zijn samengevoegd. - -### Zoekingangen van de verschillende endpoints - -Elk endpoint beschikt over een eigen set aan gegevens en elk endpoint is door middel van verschillende zoekingangen te bevragen. -In de tabel [Wat zit in welk endpoint](https://github.com/lvbag/BAG-API/blob/master/Documentatie/Tabel_Wat%20zit%20in%20welk%20endpoint_.pdf) is af te lezen welke zoekingangen mogelijk zijn bij de verschillende endpoints en welke informatie dit oplevert. - -### Algemene functionaliteit - -Er zijn een aantal algemene functies die gelden voor bovenstaande aanvragen: - - • De expand resource is te gebruiken om binnen een response extra informatie te ontvangen over een van de objecttypen. Zo kan bijvoorbeeld bij een adres de volledige informatie (inclusief registratie tijdstippen) van een openbare ruimte worden opgevraagd door expand=openbareruimte mee te nemen in de bevraging. Voor de werking, zie feature [expand.](https://github.com/lvbag/BAG-API/blob/master/Features/expand.feature) - -• De functionaliteit exacte match biedt de mogelijkheid om een specifiek object te bevragen. Ook wanneer er meerdere objecten aan de opgegeven parameters voldoen. Parameter exacteMatch=true werkt als een filter op de objecten die voldoen aan de opgegeven parameters huisnummer, huisletter en huisnummertoevoeging. De endpoints waar exacte match kan worden toegepast kennen geen fuzzy search. Voor de werking, zie feature [exacte match.](https://github.com/lvbag/BAG-API/blob/master/Features/exacte_match.feature) - -• Er wordt paginering gebruikt om het aantal zoekresultaten per zoekvraag te beperken. Met de page parameter kan een volgende pagina worden gevraagd. Met de pageSize parameter kan gekozen worden voor meer of minder zoekresultaten per pagina (standaard is 20, maximum is 100). Voor de werking, zie feature [paginering.](https://github.com/lvbag/BAG-API/blob/master/Features/paginering.feature) - -• Bij enkele endpoints wordt de mogelijkheid geboden om met de parameter Huidig alleen huidige objecten op te vragen. Huidig betekent dat het object actueel is en geen eindstatus heeft. De endpoints Adressen en Adressen uitgebreid leveren alleen huidige gegevens. Voor meer informatie, zie feature [huidig.](https://github.com/lvbag/BAG-API/blob/master/Features/huidig.feature) - -• Soms kan een onderzoek lopen naar de juistheid van een gegeven. Er zijn dan twijfels over de juistheid van de geregistreerde waarde. De API levert deze waarde wel, maar neemt die velden dan op in Inonderzoek met de waarde True. Voor de werking, zie feature [Inonderzoek bij adressen en adressenUitgebreid.](https://github.com/lvbag/BAG-API/blob/master/Features/inonderzoek-bij-adressen-en-adressen-uitgebreid.feature) - -• De gegevens die worden geleverd met de endpoints adressen en adressen uitgebreid zijn huidige gegevens. Door middel van de boolean inclusief eindstatus, is het mogelijk om ook adressen te zoeken waarbij één van de bronobjecten (nummeraanduiding, openbare ruimte en woonplaats) een eindstatus heeft. - -• Sommige resources bevatten geometrie. De API ondersteunt op dit moment alleen het RD coördinatenstelsel (epsg:28992). Bij een aanvraag die geometrie teruglevert, moet de request header Accept-Crs worden meegestuurd. - -• Bij het zoeken naar panden en adresseerbare objecten kan gebruik worden gemaakt van een boundingbox. - -### Uitwerking Use cases - -#### Zoeken op een adres d.m.v. postcode en huisnummer binnen het endpoint Adressen - -Je kan een adres zoeken met het endpoint /adressen/. Als zoekingang kan bijvoorbeeld de postcode en huisnummercombinatie worden gebruikt. - -Een volledig overzicht met mogelijke zoekingangen is opgenomen in de tabel [Wat zit in welk endpoint](https://github.com/lvbag/BAG-API/blob/master/Documentatie/Tabel_Wat%20zit%20in%20welk%20endpoint_.pdf). - -Deze zoekfunctie kan soms veel zoekresultaten opleveren. Daarom wordt hier [paginering](https://github.com/lvbag/BAG-API/blob/master/Features/paginering.feature) toegepast. - -In onderstaand voorbeeld is gezocht op postcode 2631 CR, huisnummer 15 en huisletter c. - -![image](https://user-images.githubusercontent.com/40664681/204531952-466b4e22-5fb0-4fbb-875d-320d22397057.png) - - -#### Zoeken naar alle verblijfsobjecten gelegen binnen een pand - -Wanneer je op zoek bent naar alle verblijfsobjecten die gelegen zijn binnen een pand, kan je dit doen door gebruik te maken van het verblijfsobjecten endpoint. Door de pandidentificatie als zoekingang te gebruiken, worden alle verblijfsobjecten binnen het pand geleverd. - -Dit doe je met /verblijfsobjecten?pandIdentificatie={pandIdentificatie}, waarbij {pandIdentificatie} moet worden vervangen door de identificatie van het betreffende pand. Bijvoorbeeld /adressen?pandIdentificatie=0268100000021458: - - ![image](https://user-images.githubusercontent.com/40664681/204532327-1d1547c3-f876-4cac-83c6-e2c51b2f4263.png) - - Aangezien dit veel adressen kan opleveren, wordt hier [paginering](https://github.com/lvbag/BAG-API/blob/master/Features/paginering.feature) toegepast. - - #### Zoeken naar adressen binnen een bounding box - -De BAG API biedt de mogelijkheid om binnen een specifiek gebied (bounding box) BAG gegevens op te vragen. Het is bijvoorbeeld mogelijk om door middel van een bounding box te zoeken naar adresseerbare objecten (met adresgegevens) binnen een maximum oppervlakte van 250.000 vierkante meter. - -Binnen het endpoint adresseerbare objecten kunnen de x en y coördinaten van de hoek linksonder worden opgegeven en de x en y coördinaten van de hoek rechtsboven. Deze twee punten maken een rechthoekige box waarbinnen wordt gezocht. - -Let erop dat bij de bevraging de Content-Crs epsg:28992 wordt meegegeven. - -De url is als volgt: -https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/adresseerbareobjecten?huidig=false&page=1&pageSize=20&bbox=230781.67,582665.17,230956.35,582882.42 - -![image](https://user-images.githubusercontent.com/40664681/204532827-624028b3-de6d-4dce-9d89-3137bd283f31.png) - -### Beperking gebruik BAG API Individuele Bevragingen - -Het gebruik van de BAG API Individuele Bevragingen is kosteloos. Bij het gebruik van deze service gelden voorwaarden om overmatig of onwenselijk gebruik van de API te voorkomen. We willen de BAG API voor alle afnemers snel en bruikbaar houden. Om dit te kunnen waarborgen zijn limieten ingesteld. Meer informatie over de beperkingen van de BAG API vindt u [hier.](https://github.com/lvbag/BAG-API/blob/master/Documentatie/Beperkingen%20gebruik%20BAG%20API.md) - -## Implementeer de API client - -Client code kan worden gegenereerd met de “[genereervariant](https://api.bag.kadaster.nl/lvbag/individuelebevragingen/v2/openapi.yaml)” van de API-specificaties en een code generator. Een overzicht met codegeneratoren is te vinden op [OpenAPI.Tools.](https://openapi.tools/#sdk) - -## Probeer en test de API - -De werking van de API is het gemakkelijkst te testen met behulp van [Postman](https://www.getpostman.com/). De [openapi.yaml](https://api.bag.kadaster.nl/lvbag/individuelebevragingen/v2/openapi.yaml) kan je importeren als project, waarna de verschillende requests worden ingeladen die deze API ondersteunt. - -### API Key - -Om de API te kunnen bevragen, is een API key nodig. Deze moet je bij het request opnemen in request header “X-Api-Key”. [Vraag een API key voor de BAG API aan.](https://formulieren.kadaster.nl/aanvraag_bag_api_individuele_bevragingen_productie) - -### Testgevallen - -Onderstaande tabellen bevatten testgevallen voor specifieke situaties waarmee de werking van de API kan worden getest: - - | **Resource** | **Test situatie** | **URI** | -|-----------------------|----------------------------------------------------------------------------------|-----------------------------------------| -| adressen | Adres met diakriet in straatnaam, huisnummer, huisletter en huisnummertoevoeging | /adressen/0484200002040489 | -| adressen | Lange straatnaam | /adressen/0417200000000354 | -| adressen | Nevenadres | /adressen/0014200022197986 | -| adressen | Geconstateerd | /adressen/0014200022188962 | -| adressen | Meerdere panden op zelfde adres | /adressen/0193200000096680 | -| adresseerbareobjecten | Verblijfsobject | /adresseerbareobjecten/0599010000165822 | -| adresseerbareobjecten | Standplaats | /adresseerbareobjecten/0503030000103062 | -| adresseerbareobjecten | Ligplaats | /adresseerbareobjecten/0569020000012435 | -| adresseerbareobjecten | Meerdere gebruiksdoelen | /adresseerbareobjecten/0626019900006674 | -| adresseerbareobjecten | Met nevenadres | /adresseerbareobjecten/0014010011067299 | -| adresseerbareobjecten | Meerdere panden | /adresseerbareobjecten/0193010000096628 | -| panden | Veel adressen | /panden/0826100000000467 | -| panden | Met nevenadres | /panden/0014100010921152 | -| panden | Zonder adres | /panden/0503100000034877 | - -Tip: Je kan ook de [BAG Viewer](https://bagviewer.kadaster.nl/lvbag/bag-viewer/index.html) gebruiken om meer testgevallen te zoeken. - -### URL - -De API is te benaderen via de volgende url: - -Testomgeving: -https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/ - -Productieomgeving: -https://api.bag.kadaster.nl/lvbag/individuelebevragingen/v2/ diff --git a/docs/getting-started.md b/docs/getting-started.md index 8cb02dd8..833fdc44 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,90 +1,129 @@ --- layout: page-with-side-nav -title: Functionaliteit en specificaties +title: Getting Started --- -# Functionaliteit en specificaties - BAG Huidige Bevragingen API - -## De BAG Huidige Bevragingen API v 1.5 is deprecated en wordt met ingang van 1 juli a.s. niet meer ondersteund. +# Getting Started + +Om aan te sluiten kun je de volgende stappen doorlopen: +1. [Aanmelden om toegang te krijgen tot de acceptatie- en productieomgeving](#aanmelden) +2. [Bekijk de functionaliteit en specificaties](#functionaliteiten-en-specificaties) +3. [Implementeer de API Client](#implementeer-de-api-client) +4. [Probeer en test de API](#probeer-en-test-de-api) + +## Aanmelden + +[Vraag een API key voor de test- en productieomgeving aan.](https://formulieren.kadaster.nl/aanvraag_bag_api_individuele_bevragingen_productie) +Testen wordt bij voorkeur gedaan in de testomgeving. + +## Functionaliteiten en specificaties + +Je kunt de Open API Specificaties (OAS3) van de API bekijken in [Swagger-formaat](https://lvbag.github.io/BAG-API/Technische%20specificatie/) of [Redoc.](https://lvbag.github.io/BAG-API/Technische%20specificatie/Redoc/) +De (resolved) OAS3 is hier te downloaden: [openapi.yaml](https://api.bag.kadaster.nl/lvbag/individuelebevragingen/v2/openapi.yaml). + +### Beschikbare endpoints + +De API kent de volgende endpoints: + +* *Woonplaatsen* +* *Openbare ruimten* +* *Nummeraanduidingen* +* *Verblijfsobjecten* +* *Standplaatsen* +* *Ligplaatsen* +* *Panden* +* *Bronhouders* +* *Adressen*:
hierin zijn samenhangende en gerelateerde gegevens samengevoegd uit de nummeraanduiding, openbare ruimte en woonplaats die samen een adres vormen. +* *Adressen uitgebreid*:
deze resource ondersteunt de mogelijkheid om met één bevraging meer informatie over het adres op te halen, zoals het bouwjaar en de gebruiksoppervlakte. +* *Adresseerbare objecten*:
dit kan een verblijfsobject, ligplaats of standplaats zijn. + +De objecten endpoints leveren één of meer (voorkomens van) object(en), met embedded resources en links. + +De endpoints *Adressen* en *Adressen uitgebreid* en *Adresseerbare objecten* zijn samengestelde (convenience) endpoints waarin de gegevens van verschillende BAG objecten zijn samengevoegd. + +### Zoekingangen van de verschillende endpoints + +Elk endpoint beschikt over een eigen set aan gegevens en elk endpoint is door middel van verschillende zoekingangen te bevragen. +In de tabel [Wat zit in welk endpoint](https://github.com/lvbag/BAG-API/blob/master/Documentatie/Tabel_Wat%20zit%20in%20welk%20endpoint_.pdf) is af te lezen welke zoekingangen mogelijk zijn bij de verschillende endpoints en welke informatie dit oplevert. + +### Algemene functionaliteit + +Er zijn een aantal algemene functies die gelden voor bovenstaande aanvragen: + +* De expand resource is te gebruiken om binnen een response extra informatie te ontvangen over een van de objecttypen. Zo kan bijvoorbeeld bij een adres de volledige informatie (inclusief registratie tijdstippen) van een openbare ruimte worden opgevraagd door expand=openbareruimte mee te nemen in de bevraging. Voor de werking, zie feature [expand.](https://github.com/lvbag/BAG-API/blob/master/Features/expand.feature) + +* De functionaliteit exacte match biedt de mogelijkheid om een specifiek object te bevragen. Ook wanneer er meerdere objecten aan de opgegeven parameters voldoen. Parameter exacteMatch=true werkt als een filter op de objecten die voldoen aan de opgegeven parameters huisnummer, huisletter en huisnummertoevoeging. De endpoints waar exacte match kan worden toegepast kennen geen fuzzy search. Voor de werking, zie feature [exacte match.](https://github.com/lvbag/BAG-API/blob/master/Features/exacte_match.feature) + +* Er wordt paginering gebruikt om het aantal zoekresultaten per zoekvraag te beperken. Met de page parameter kan een volgende pagina worden gevraagd. Met de pageSize parameter kan gekozen worden voor meer of minder zoekresultaten per pagina (standaard is 20, maximum is 100). Voor de werking, zie feature [paginering.](https://github.com/lvbag/BAG-API/blob/master/Features/paginering.feature) + +* Bij enkele endpoints wordt de mogelijkheid geboden om met de parameter Huidig alleen huidige objecten op te vragen. Huidig betekent dat het object actueel is en geen eindstatus heeft. De endpoints Adressen en Adressen uitgebreid leveren alleen huidige gegevens. Voor meer informatie, zie feature [huidig.](https://github.com/lvbag/BAG-API/blob/master/Features/huidig.feature) + +* Soms kan een onderzoek lopen naar de juistheid van een gegeven. Er zijn dan twijfels over de juistheid van de geregistreerde waarde. De API levert deze waarde wel, maar neemt die velden dan op in Inonderzoek met de waarde True. Voor de werking, zie feature [Inonderzoek bij adressen en adressenUitgebreid.](https://github.com/lvbag/BAG-API/blob/master/Features/inonderzoek-bij-adressen-en-adressen-uitgebreid.feature) + +* De gegevens die worden geleverd met de endpoints adressen en adressen uitgebreid zijn huidige gegevens. Door middel van de boolean inclusief eindstatus, is het mogelijk om ook adressen te zoeken waarbij één van de bronobjecten (nummeraanduiding, openbare ruimte en woonplaats) een eindstatus heeft. + +* Sommige resources bevatten geometrie. De API ondersteunt op dit moment alleen het RD coördinatenstelsel (epsg:28992). Bij een aanvraag die geometrie teruglevert, moet de request header Accept-Crs worden meegestuurd. + +* Bij het zoeken naar panden en adresseerbare objecten kan gebruik worden gemaakt van een boundingbox. + +### Uitwerking Use cases + +#### Zoeken op een adres d.m.v. postcode en huisnummer binnen het endpoint Adressen + +Je kan een adres zoeken met het endpoint /adressen/. Als zoekingang kan bijvoorbeeld de postcode en huisnummercombinatie worden gebruikt. + +Een volledig overzicht met mogelijke zoekingangen is opgenomen in de tabel [Wat zit in welk endpoint](https://github.com/lvbag/BAG-API/blob/master/Documentatie/Tabel_Wat%20zit%20in%20welk%20endpoint_.pdf). + +Deze zoekfunctie kan soms veel zoekresultaten opleveren. Daarom wordt hier [paginering](https://github.com/lvbag/BAG-API/blob/master/Features/paginering.feature) toegepast. + +In onderstaand voorbeeld is gezocht op postcode 2631 CR, huisnummer 15 en huisletter c. + +![image](https://user-images.githubusercontent.com/40664681/204531952-466b4e22-5fb0-4fbb-875d-320d22397057.png) + + +#### Zoeken naar alle verblijfsobjecten gelegen binnen een pand + +Wanneer je op zoek bent naar alle verblijfsobjecten die gelegen zijn binnen een pand, kan je dit doen door gebruik te maken van het verblijfsobjecten endpoint. Door de pandidentificatie als zoekingang te gebruiken, worden alle verblijfsobjecten binnen het pand geleverd. + +Dit doe je met /verblijfsobjecten?pandIdentificatie={pandIdentificatie}, waarbij {pandIdentificatie} moet worden vervangen door de identificatie van het betreffende pand. Bijvoorbeeld /adressen?pandIdentificatie=0268100000021458: + + ![image](https://user-images.githubusercontent.com/40664681/204532327-1d1547c3-f876-4cac-83c6-e2c51b2f4263.png) -Wij adviseren niet meer te starten met de implementatie van deze API en verwijzen je naar de [Getting Started van de BAG Individuele Bevragingen v. 2.6](https://vng-realisatie.github.io/Haal-Centraal-BAG-bevragen/getting-started-IB) die deze API gaat vervangen. Onderstaande informatie is alleen bedoelt voor de huidige gebruikers van deze API. - -Je kunt de Open API Specificaties (OAS3) van de API bekijken in [Swagger-formaat](./swagger-ui) of [Redoc](./redoc). - -De (resolved) OAS3 is hier te downloaden: [openapi.yaml](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/blob/master/specificatie/genereervariant/openapi.yaml){:target="_blank" rel="noopener"}. - -## Beschikbare resources -De API kent de volgende resources: -- adressen: hierin zijn samenhangende en gerelateerde gegevens samengevoegd uit de nummeraanduiding, openbare ruimte en woonplaats die samen een adres vormen -- adresseerbareobjecten: dit kan een verblijfsobject, ligplaats of standplaats zijn -- nummeraanduidingen -- openbareruimten -- woonplaatsen -- panden - -Voor de verschillende resources wordt de uri samengesteld met de identificatie van het onderliggende BAG-object. Dit is een 16 cijferige, of in geval van woonplaats 4 cijferige identificatie. Voor adressen wordt de nummeraanduiding identificatie gebruikt in de uri. -De identificatie kan voorloopnullen bevatten, dus het is geen integer. - -### Zoeken van een adres -Je kan een adres zoeken met endpoint /adressen/zoek en parameter "zoek" waarin met postcode, woonplaats, straatnaam, huisnummer, huisletter en huisnummertoevoeging kan worden gezocht. Op dit moment worden alleen deze gegevens ondersteund, het is de bedoeling dat dit later volledig "fuzzy search" wordt. -Deze zoekfunctie, via endpoint /adressen/zoek levert voor elk gevonden adres een combinatie van een zoekresultaat identificatie en een omschrijving, plus een link voor het ophalen van de volledige adresgegevens. - -Deze zoekfunctie kan soms veel zoekresultaten opleveren. Daarom wordt hier [paginering](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.1.0/features/paginering.feature){:target="_blank"} toegepast. - -Op basis van de zoekresultaten kan je een gevonden adres ophalen met endpoint /adressen?zoekresultaatIdentificatie={zoekresultaatIdentificatie}, waarbij je {zoekresultaatIdentificatie} moet vervangen door een waarde voor identificatie in de zoekresultaten van /adressen/zoek. - -Bijvoorbeeld zoeken op "/adressen/zoek?zoek=nootdorp 15c dorpsstraat" levert: -``` -"_embedded" : { - "zoekresultaten" : [ - { - "omschrijving" : "Dorpsstraat 15c, 2631CR Nootdorp", - "identificatie" : "adr-89d5a4d96f09c60716c4671fdb9334b8", - "_links" : { - "adres" : { - "href" : "/adressen?zoekresultaatIdentificatie=adr-89d5a4d96f09c60716c4671fdb9334b8" - } - } - } - ] -} -``` -Het adres haal je vervolgens op met "/adressen?zoekresultaatIdentificatie=adr-89d5a4d96f09c60716c4671fdb9334b8". - -### Zoeken van adressen in een pand -Wanneer je alle adressen in een pand wilt zoeken, kan je dit doen met /adressen?pandIdentificatie={pandIdentificatie}, waarbij {pandIdentificatie} moet worden vervangen door de identificatie van het betreffende pand. Bijvoorbeeld /adressen?pandIdentificatie=0826100000000467. - -Aangezien dit veel adressen kan opleveren, wordt hier [paginering](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.1.0/features/paginering.feature){:target="_blank"} toegepast. - -Met dit endpoint kun je ook zoeken op postcode, huisnummer, huisletter en huisnummertoevoeging. -De manier waarop je met de parameter exacteMatch kunt zoeken, kun je vinden in de feature. - -### Geometrie van een woonplaats -De geometrie van een woonplaats kan zeer omvangrijk zijn. Daarom wordt de geometrie niet standaard met een woonplaats meegeleverd. Wanneer je de geometrie van de woonplaats wel wilt krijgen, dan moet je de expand parameter gebruiken. Bijvoorbeeld /woonplaatsen/2258?expand=geometrie. - -## Algemene functionaliteit -Verder zijn er nog een paar algemene functies die gelden voor alle bovenstaande aanvragen: -- Gebruik van de **fields** parameter om de response te filteren. Voor werking, zie feature [fields](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.1.0/features/fields.feature){:target="_blank"} -- Gebruik van de **expand** parameter om subresources te ontsluiten. Voor werking, zie feature [expand](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.1.0/features/expand.feature){:target="_blank"} -- Gebruik van paginering om het aantal zoekresultaten per zoekvraag te beperken. Met de **page** parameter kan een volgende pagina worden gevraagd. Met de **pageSize** parameter kan gekozen worden voor meer of minder zoekresultaten per pagina (standaard is 20, maximum is 100). Voor werking, zie feature [paginering](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.1.0/features/paginering.feature){:target="_blank"} -- Soms kan er een onderzoek lopen of een gegeven wel correct is. Er zijn dan twijfels over de juistheid van de geregistreerde waarde. De API levert deze waarde wel, maar neemt die velden dan op in **mogelijkOnjuist** met de waarde True. -- Sommige resources bevatten geometrie. De API ondersteunt op dit moment alleen het RD coördinatenstelsel (epsg:28992). Bij een aanvraag die geometrie teruglevert moet de request header **Accept-Crs** worden meegestuurd. -- Bij het zoeken van een pand op **locatie** mag de header **Content-Crs** worden meegestuurd. Wanneer je deze header weglaat wordt default coördinatenstelsel RD (epsg:28992) gebruikt wat op dit moment ook het enige het coördinatenstelsel is dat de API ondersteunt. -- Bij het zoeken naar panden en adresseerbare objecten kun je gebruik maken van bbox. -- [HAL links](https://tools.ietf.org/html/draft-kelly-json-hal-08){:target="_blank"}, die soms [templated](https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/v1.1.0/features/uri-templating.feature){:target="_blank"} worden geleverd. - -## Test de API -De werking van de API is het makkelijkst te testen met behulp van [Postman](https://www.getpostman.com/){:target="_blank"}. -De [openapi.yaml](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/blob/master/specificatie/genereervariant/openapi.yaml){:target="_blank"} kun je importeren als project, waarna de verschillende requests worden ingeladen die deze API ondersteunt. -We hebben al een project voor je gemaakt die je kan gebruiken: [BAG-Bevragen-postman-collection.json](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/blob/master/test/BAG-Bevragen-postman-collection.json){:target="_blank"}. Hierin moet je alleen de base url en authenticatie (API-key) nog invullen. - -### API key -Om de API te kunnen bevragen is de API key nodig die je al eerder hebt ontvangen. Deze moet je bij het request opnemen in request header "X-Api-Key". - -### Testgevallen -Onderstaande tabellen bevatten testgevallen voor specifieke situaties waarmee de werking van de API kan worden getest. - -| Resource | Testsituatie | uri | -| --------------------- | -------------------------------------------------------------------------------- | --------------------------------------- | + Aangezien dit veel adressen kan opleveren, wordt hier [paginering](https://github.com/lvbag/BAG-API/blob/master/Features/paginering.feature) toegepast. + + #### Zoeken naar adressen binnen een bounding box + +De BAG API biedt de mogelijkheid om binnen een specifiek gebied (bounding box) BAG gegevens op te vragen. Het is bijvoorbeeld mogelijk om door middel van een bounding box te zoeken naar adresseerbare objecten (met adresgegevens) binnen een maximum oppervlakte van 250.000 vierkante meter. + +Binnen het endpoint adresseerbare objecten kunnen de x en y coördinaten van de hoek linksonder worden opgegeven en de x en y coördinaten van de hoek rechtsboven. Deze twee punten maken een rechthoekige box waarbinnen wordt gezocht. + +Let erop dat bij de bevraging de Content-Crs epsg:28992 wordt meegegeven. + +De url is als volgt: +https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/adresseerbareobjecten?huidig=false&page=1&pageSize=20&bbox=230781.67,582665.17,230956.35,582882.42 + +![image](https://user-images.githubusercontent.com/40664681/204532827-624028b3-de6d-4dce-9d89-3137bd283f31.png) + +### Beperking gebruik BAG API Individuele Bevragingen + +Het gebruik van de BAG API Individuele Bevragingen is kosteloos. Bij het gebruik van deze service gelden voorwaarden om overmatig of onwenselijk gebruik van de API te voorkomen. We willen de BAG API voor alle afnemers snel en bruikbaar houden. Om dit te kunnen waarborgen zijn limieten ingesteld. Meer informatie over de beperkingen van de BAG API vindt u [hier.](https://github.com/lvbag/BAG-API/blob/master/Documentatie/Beperkingen%20gebruik%20BAG%20API.md) + +## Implementeer de API client + +Client code kan worden gegenereerd met de “[genereervariant](https://api.bag.kadaster.nl/lvbag/individuelebevragingen/v2/openapi.yaml)” van de API-specificaties en een code generator. Een overzicht met codegeneratoren is te vinden op [OpenAPI.Tools.](https://openapi.tools/#sdk) +## Probeer en test de API + +De werking van de API is het gemakkelijkst te testen met behulp van [Postman](https://www.getpostman.com/). De [openapi.yaml](https://api.bag.kadaster.nl/lvbag/individuelebevragingen/v2/openapi.yaml) kan je importeren als project, waarna de verschillende requests worden ingeladen die deze API ondersteunt. + +### API Key + +Om de API te kunnen bevragen, is een API key nodig. Deze moet je bij het request opnemen in request header “X-Api-Key”. [Vraag een API key voor de BAG API aan.](https://formulieren.kadaster.nl/aanvraag_bag_api_individuele_bevragingen_productie) + +### Testgevallen + +Onderstaande tabellen bevatten testgevallen voor specifieke situaties waarmee de werking van de API kan worden getest: + + | **Resource** | **Test situatie** | **URI** | +|-----------------------|----------------------------------------------------------------------------------|-----------------------------------------| | adressen | Adres met diakriet in straatnaam, huisnummer, huisletter en huisnummertoevoeging | /adressen/0484200002040489 | | adressen | Lange straatnaam | /adressen/0417200000000354 | | adressen | Nevenadres | /adressen/0014200022197986 | @@ -99,8 +138,15 @@ Onderstaande tabellen bevatten testgevallen voor specifieke situaties waarmee de | panden | Veel adressen | /panden/0826100000000467 | | panden | Met nevenadres | /panden/0014100010921152 | | panden | Zonder adres | /panden/0503100000034877 | - -Tip: Je kan ook de [BAG Viewer](https://bagviewer.kadaster.nl/lvbag/bag-viewer/index.html){:target="_blank"} gebruiken om meer testgevallen te zoeken. - -### URL -De API is te benaderen via de volgende url: https://api.bag.kadaster.nl/esd/huidigebevragingen/v1. + +Tip: Je kan ook de [BAG Viewer](https://bagviewer.kadaster.nl/lvbag/bag-viewer/index.html) gebruiken om meer testgevallen te zoeken. + +### URL + +De API is te benaderen via de volgende url: + +**Testomgeving**: +https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/ + +**Productieomgeving**: +https://api.bag.kadaster.nl/lvbag/individuelebevragingen/v2/ diff --git a/docs/index.md b/docs/index.md index 455714f1..b76aa794 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,23 +1,23 @@ --- layout: page-with-side-nav -title: Haal Centraal BAG Huidige Bevragingen +title: BAG Individuele Bevragingen --- -# Haal Centraal BAG Huidige Bevragingen wordt geintegreerd in BAG Individuele Bevragingen! +# BAG Individuele Bevragingen -Deze API voor het zoeken en raadplegen van adressen, adresseerbaar objecten en panden uit de Basisregistratie Adressen en Gebouwen (BAG) wordt geintegreerd in de BAG API Individuele Bevragingen. Als gebruiker van de BAG API Huidige Bevragingen heb je tot 1 juli 2023 de tijd om over te stappen. +BAG Individuele bevragingen is een API voor het zoeken en raadplegen van gegevens in de basisregistratie Adressen en Gebouwen voor alle binnengemeentelijke afnemers in NL, maar ook voor waterschappen, belastingsamenwerkingen en andere overheden. We doen ons uiterste best om de API evolvable door te ontwikkelen en geen breaking changes te introduceren. -Tijdens de doorontwikkeling die de afgelopen jaren heeft plaatsgevonden, zijn de beide BAG API’s dusdanig naar elkaar toe gegroeid, dat het efficiënter is om de BAG API’s te integreren. Het Kadaster en VNG Realisatie hebben de afgelopen maanden gewerkt aan de integratie van de twee BAG API’s: Huidige Bevragingen (Haal Centraal) en Individuele Bevragingen. Alle functionaliteiten van de BAG API Huidige Bevragingen zijn nu toegevoegd aan de BAG API Individuele Bevragingen. Zodra de nieuwe versie van BAG Individuele Bevragingen in productie gaat, vind je de specificaties en de Getting Started van de BAG Individuele Bevragingen API op deze website. +Bekijk de [release notes](./releasenotes.md) van deze release. Bezoek de [GitHub repository](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/). # Direct aan de slag? -* Bekijk de specificaties met [Swagger UI](./swagger-ui-IB) of [Redoc](./redoc-IB) -* Lees de [Getting started](./getting-started-IB) -* Download de [technische specificaties](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/blob/master/specificatie/genereervariant/openapi.yaml){:target="_blank"} +* Bekijk de specificaties met [Swagger UI](./swagger-ui) of [Redoc](./redoc) +* Lees de [Getting started](./getting-started) +* Download de [technische specificaties](https://github.com/lvbag/BAG-API/blob/master/Technische%20specificatie/Archief/Yaml's/BAG%20API%20Individuele%20Bevragingen/resolved/individuelebevragingen/v2/openapi.yaml){:target="_blank"} * [Vraag een API-key aan](https://formulieren.kadaster.nl/aanvraag_bag_api_individuele_bevragingen_productie){:target="_blank"} voor toegang tot de productieomgeving. ## Bronnen @@ -25,7 +25,7 @@ Bezoek de [GitHub repository](https://github.com/VNG-Realisatie/Haal-Centraal-BA * [API Design Visie](https://github.com/Geonovum/KP-APIs/blob/master/overleggen/Werkgroep%20API%20design%20visie/API%20Design%20Visie.md){:target="_blank" rel="noopener"} * [REST API Design Rules](https://docs.geostandaarden.nl/api/API-Designrules/){:target="_blank" rel="noopener"} * [Landelijke API strategie voor de overheid](https://geonovum.github.io/KP-APIs/){:target="_blank" rel="noopener"} -* [Stelselcatalogus](https://www.stelselcatalogus.nl/registraties/BAG/){:target="_blank" rel="noopener"} +* [Stelselcatalogus](https://www.stelselcatalogus.nl/registraties/registratie?id=http://opendata.stelselcatalogus.nl/id/registratie/BAG){:target="_blank" rel="noopener"} ## Contact diff --git a/docs/redoc-HB.md b/docs/redoc-HB.md new file mode 100644 index 00000000..9bb039e8 --- /dev/null +++ b/docs/redoc-HB.md @@ -0,0 +1,7 @@ +--- +layout: page-with-side-nav +title: redoc +body_include: redoc-body.html +spec-url: https://raw.githubusercontent.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/master/specificatie/genereervariant/openapi.yaml +--- + diff --git a/docs/redoc-IB.md b/docs/redoc-IB.md deleted file mode 100644 index ed1c986e..00000000 --- a/docs/redoc-IB.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: page-with-side-nav -title: redoc -body_include: redoc-body.html -spec-url: https://raw.githubusercontent.com/lvbag/BAG-API/master/Technische%20specificatie/Archief/Yaml%27s/BAG%20API%20Individuele%20Bevragingen/resolved/individuelebevragingen/v2/openapi.yaml ---- - diff --git a/docs/redoc.md b/docs/redoc.md index 6318bb8d..ed1c986e 100644 --- a/docs/redoc.md +++ b/docs/redoc.md @@ -2,6 +2,6 @@ layout: page-with-side-nav title: redoc body_include: redoc-body.html -spec-url: https://raw.githubusercontent.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/master/specificatie/genereervariant/openapi.yaml +spec-url: https://raw.githubusercontent.com/lvbag/BAG-API/master/Technische%20specificatie/Archief/Yaml%27s/BAG%20API%20Individuele%20Bevragingen/resolved/individuelebevragingen/v2/openapi.yaml --- - \ No newline at end of file + diff --git a/docs/swagger-ui-HB.md b/docs/swagger-ui-HB.md new file mode 100644 index 00000000..eb5701ed --- /dev/null +++ b/docs/swagger-ui-HB.md @@ -0,0 +1,8 @@ +--- +layout: page-with-side-nav +title: swagger-ui +head_include: swagger-ui-head.html +body_include: swagger-ui-body.html +openapi-url: https://raw.githubusercontent.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/master/specificatie/genereervariant/openapi.yaml +--- +
diff --git a/docs/swagger-ui-IB.md b/docs/swagger-ui-IB.md deleted file mode 100644 index 6c1a7855..00000000 --- a/docs/swagger-ui-IB.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -layout: page-with-side-nav -title: swagger-ui -head_include: swagger-ui-head.html -body_include: swagger-ui-body.html -openapi-url: https://raw.githubusercontent.com/lvbag/BAG-API/master/Technische%20specificatie/Archief/Yaml's/BAG%20API%20Individuele%20Bevragingen/resolved/individuelebevragingen/v2/openapi.yaml ---- -
diff --git a/docs/swagger-ui.md b/docs/swagger-ui.md index eb5701ed..6c1a7855 100644 --- a/docs/swagger-ui.md +++ b/docs/swagger-ui.md @@ -3,6 +3,6 @@ layout: page-with-side-nav title: swagger-ui head_include: swagger-ui-head.html body_include: swagger-ui-body.html -openapi-url: https://raw.githubusercontent.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/master/specificatie/genereervariant/openapi.yaml +openapi-url: https://raw.githubusercontent.com/lvbag/BAG-API/master/Technische%20specificatie/Archief/Yaml's/BAG%20API%20Individuele%20Bevragingen/resolved/individuelebevragingen/v2/openapi.yaml ---
diff --git a/docs/user-stories-prod-IB.md b/docs/user-stories-prod-HB.md similarity index 98% rename from docs/user-stories-prod-IB.md rename to docs/user-stories-prod-HB.md index fd9345aa..56ca8609 100644 --- a/docs/user-stories-prod-IB.md +++ b/docs/user-stories-prod-HB.md @@ -1,11 +1,11 @@ --- layout: page-with-side-nav -title: User Stories in Productie in BAG individuele Bevragingen +title: User Stories in Productie --- # User stories -## Vanaf versie 2.6 +## Vanaf versie 1.4 - [Als medewerker gebiedsontwikkeling wil ik op bouwjaar (range, ouder dan, jonger dan) appartements-adressen in een bepaald gebied kunnen zoeken](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/380){:target="_blank" rel="noopener"} - [Als medewerker van de gemeente die personen in een gebied wil zoeken en aanschrijven/contacten wil ik direct een collectie adressen en/of ado's terugkrijgen](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/373){:target="_blank" rel="noopener"} @@ -17,13 +17,22 @@ title: User Stories in Productie in BAG individuele Bevragingen - [Als medewerker gebiedsontwikkeling wil ik op basis van bepaalde kenmerken van appartements-adressen/verblijfsobjecten zoals bouwjaar Pand (en energielabel) in een bepaald gebied kunnen zoeken](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/306){:target="_blank" rel="noopener"} - [Als medewerker stadsbeheer wil ik bewoners in een bepaald gebied kunnen aanschrijven ](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/19){:target="_blank" rel="noopener"} - [Als medewerker monumentenzorg wil ik het perceel of het pand kunnen aanwijzen op de kaart ](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/4){:target="_blank" rel="noopener"} + +## Vanaf versie 1.3 + - [zoeken op postcode toestaan met spatie tussen cijfers en letters](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/442){:target="_blank" rel="noopener"} - [Als gebruikers van de API wil ik exact kunnen zoeken zoeken op postcode en huisnummer](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/404){:target="_blank" rel="noopener"} - [Als gebruiker van de API wil ik bij het vragen van een adres direct het bijbehorende adresseerbaar object krijgen](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/403){:target="_blank" rel="noopener"} + +## Vanaf versie 1.2 + - [als developer van de BRK API wil ik de korteNaam kunnen leveren bij het adres van een kadastraal object](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/363){:target="_blank" rel="noopener"} - [als gebruiker wil ik het samengesteld adres krijgen](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/360){:target="_blank" rel="noopener"} - [Als gebruiker wil ik de inhoud van de mogelijkOnjuist gegevensgroep kunnen filteren](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/294){:target="_blank" rel="noopener"} - [Expand gerelateerde resource als relatie in onderzoek is](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/293){:target="_blank" rel="noopener"} + +## Vanaf versie 1.1 + - [Als medewerker vergunningen en burgerzaken wil ik net zo'n informatierijke toelichting voor gecontateerd als voor mogelijkOnjuist](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/128){:target="_blank" rel="noopener"} - [Als medewerker burgerzaken wil ik een adres raadplegen uit de BRP met de nummeraanduidingidentificatie](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/32){:target="_blank" rel="noopener"} - [Als burger wil ik een adres kunnen selecteren](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/18){:target="_blank" rel="noopener"} diff --git a/docs/user-stories-prod.md b/docs/user-stories-prod.md index 56ca8609..fd9345aa 100644 --- a/docs/user-stories-prod.md +++ b/docs/user-stories-prod.md @@ -1,11 +1,11 @@ --- layout: page-with-side-nav -title: User Stories in Productie +title: User Stories in Productie in BAG individuele Bevragingen --- # User stories -## Vanaf versie 1.4 +## Vanaf versie 2.6 - [Als medewerker gebiedsontwikkeling wil ik op bouwjaar (range, ouder dan, jonger dan) appartements-adressen in een bepaald gebied kunnen zoeken](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/380){:target="_blank" rel="noopener"} - [Als medewerker van de gemeente die personen in een gebied wil zoeken en aanschrijven/contacten wil ik direct een collectie adressen en/of ado's terugkrijgen](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/373){:target="_blank" rel="noopener"} @@ -17,22 +17,13 @@ title: User Stories in Productie - [Als medewerker gebiedsontwikkeling wil ik op basis van bepaalde kenmerken van appartements-adressen/verblijfsobjecten zoals bouwjaar Pand (en energielabel) in een bepaald gebied kunnen zoeken](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/306){:target="_blank" rel="noopener"} - [Als medewerker stadsbeheer wil ik bewoners in een bepaald gebied kunnen aanschrijven ](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/19){:target="_blank" rel="noopener"} - [Als medewerker monumentenzorg wil ik het perceel of het pand kunnen aanwijzen op de kaart ](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/4){:target="_blank" rel="noopener"} - -## Vanaf versie 1.3 - - [zoeken op postcode toestaan met spatie tussen cijfers en letters](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/442){:target="_blank" rel="noopener"} - [Als gebruikers van de API wil ik exact kunnen zoeken zoeken op postcode en huisnummer](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/404){:target="_blank" rel="noopener"} - [Als gebruiker van de API wil ik bij het vragen van een adres direct het bijbehorende adresseerbaar object krijgen](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/403){:target="_blank" rel="noopener"} - -## Vanaf versie 1.2 - - [als developer van de BRK API wil ik de korteNaam kunnen leveren bij het adres van een kadastraal object](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/363){:target="_blank" rel="noopener"} - [als gebruiker wil ik het samengesteld adres krijgen](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/360){:target="_blank" rel="noopener"} - [Als gebruiker wil ik de inhoud van de mogelijkOnjuist gegevensgroep kunnen filteren](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/294){:target="_blank" rel="noopener"} - [Expand gerelateerde resource als relatie in onderzoek is](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/293){:target="_blank" rel="noopener"} - -## Vanaf versie 1.1 - - [Als medewerker vergunningen en burgerzaken wil ik net zo'n informatierijke toelichting voor gecontateerd als voor mogelijkOnjuist](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/128){:target="_blank" rel="noopener"} - [Als medewerker burgerzaken wil ik een adres raadplegen uit de BRP met de nummeraanduidingidentificatie](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/32){:target="_blank" rel="noopener"} - [Als burger wil ik een adres kunnen selecteren](https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/issues/18){:target="_blank" rel="noopener"} diff --git a/docs/user-stories.md b/docs/user-stories.md deleted file mode 100644 index 36504e24..00000000 --- a/docs/user-stories.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: page-with-side-nav -title: user stories ---- -# User stories - -Bekijk de user stories in [GitHub](https://github.com/VNG-Realisatie{{ site.baseurl }}/issues?q=is%3Aopen+is%3Aissue+label%3A%22user+story%22){:target="_blank"}