Getting Started

To connect, you can go through the following steps:

1. Register to obtain access to the acceptance and production environments
2. View the functionality and specifications
3. Implement the API client
4. Try and test the API

Registering

Request an API key for the test and production environments. Testing is preferably done in the test environment.

Functionality and specifications

You can view the Open API Specifications (OAS3) of the API in Swagger format or Redoc. The (resolved) OAS3 can be downloaded here: openapi.yaml.

Available endpoints

The API has the following endpoints:

• Woonplaatsen
• Openbare ruimten
• Nummeraanduidingen
• Verblijfsobjecten
• Standplaatsen
• Ligplaatsen
• Panden
• Bronhouders
• Adressen: here, coherent and related data from the nummeraanduiding, openbare ruimte and woonplaats that together form an address is combined.
• Adressen uitgebreid: this resource supports the possibility of retrieving more information about the address in a single query, such as the year of construction and the usable floor area.
• Adresseerbare objecten: this can be a verblijfsobject, ligplaats or standplaats.

The object endpoints supply one or more (occurrences of) objects, with embedded resources and links.

The endpoints Adressen, Adressen uitgebreid and Adresseerbare objecten are composite (convenience) endpoints in which the data of different BAG objects is combined.

Search entries of the various endpoints

Every endpoint has its own set of data and every endpoint can be queried through different search entries. The table Wat zit in welk endpoint shows which search entries are possible for the various endpoints and what information this yields.

General functionality

There are a number of general functions that apply to the requests above:

• The expand resource can be used to receive extra information about one of the object types within a response. For example, for an address the full information (including registration times) of a public space can be requested by including expand=openbareruimte in the query. For its behaviour, see the feature expand.
• The exact match functionality offers the possibility of querying a specific object, even where several objects meet the parameters supplied. The parameter exacteMatch=true works as a filter on the objects that meet the parameters huisnummer, huisletter and huisnummertoevoeging supplied. The endpoints where exact match can be applied have no fuzzy search. For its behaviour, see the feature exacte match.
• Paging is used to limit the number of search results per query. With the page parameter a next page can be requested. With the pageSize parameter you can choose more or fewer search results per page (the default is 20, the maximum is 100). For its behaviour, see the feature paginering.
• For a few endpoints there is the possibility of requesting only current objects with the parameter Huidig. Current means that the object is current and has no end status. The endpoints Adressen and Adressen uitgebreid supply only current data. For more information, see the feature huidig.
• Sometimes an investigation may be under way into the correctness of an item of data. There are then doubts about the correctness of the value registered. The API does supply this value, but then includes those fields in Inonderzoek with the value True. For its behaviour, see the feature Inonderzoek.
• The data supplied by the endpoints adressen and adressen uitgebreid is current data. By means of the boolean inclusief eindstatus it is possible also to search for addresses where one of the source objects (nummeraanduiding, openbare ruimte and woonplaats) has an end status.
• Some resources contain geometry. The API currently supports only the RD coordinate system (epsg:28992). For a request that returns geometry, the request header Accept-Crs must be sent along.
• When searching for panden and adresseerbare objecten, a bounding box can be used.

Use cases worked out

Searching for an address by postal code and house number within the Adressen endpoint

You can search for an address with the endpoint /adressen/. As a search entry, the combination of postal code and house number can be used, for example.

A complete overview of possible search entries is included in the table Wat zit in welk endpoint.

This search function can sometimes yield many search results. That is why paging is applied here.

In the example below, a search was made for postal code 2631 CR, house number 15 and house letter c.

{
  "_links": {
    "self": {
      "href": "https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/adressen?postcode=2631CR&huisnummer=15&huisletter=C&page=1&pageSize=20"
    }
  },
  "_embedded": {
    "adressen": [
      {
        "openbareRuimteNaam": "Dorpsstraat",
        "korteNaam": "Dorpsstraat",
        "huisnummer": 15,
        "huisletter": "c",
        "postcode": "2631CR",
        "woonplaatsNaam": "Nootdorp",
        "nummeraanduidingIdentificatie": "1926200000508011",
        "openbareRuimteIdentificatie": "1926300000479027",
        "woonplaatsIdentificatie": "1142",
        "adresseerbaarObjectIdentificatie": "1926010000508012",
        "pandIdentificaties": [
          "1926100000485708"
        ],
        "adresregel5": "Dorpsstraat 15 c",
        "adresregel6": "2631 CR  NOOTDORP",
        "_links": {
          "self": {
            "href": "https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/adressen/1926200000508011"
          },
          "openbareRuimte": {
            "href": "https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/openbareruimten/1926300000479027"
          },
          "nummeraanduiding": {
            "href": "https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/nummeraanduidingen/1926200000508011"
          },
          "woonplaats": {
            "href": "https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/woonplaatsen/1142"
          },
          "adresseerbaarObject": {
            "href": "https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/verblijfsobjecten/1926010000508012"
          },
          "panden": [
            {
              "href": "https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/panden/1926100000485708"
            }
          ]
        }
      }
    ]
  }
}

Searching for all dwellings located within a building

When you are looking for all dwellings located within a building, you can do this by using the verblijfsobjecten endpoint. By using the pandidentificatie as a search entry, all dwellings within the building are supplied.

You do this with /verblijfsobjecten?pandIdentificatie={pandIdentificatie}, where {pandIdentificatie} must be replaced by the identification of the building concerned. For example /adressen?pandIdentificatie=0268100000021458.

As this can yield many addresses, paging is applied here.

https://api.bag.kadaster.nl/lvbag/individuelebevragingen/v2/verblijfsobjecten?pandIdentificatie=0268100000021458

{
  "_embedded": {
    "verblijfsobjecten": [
      {
        "verblijfsobject": {
          "type": "Verblijfsobject",
          "heeftAlsHoofdAdres": "0268200000041560",
          "identificatie": "0268010000036826",
          "domein": "NL.IMBAG.Verblijfsobject",
          "geometrie": {
            "punt": {
              "type": "Point",
              "coordinates": [
                183003.794,
                425425.693,
                0
              ]
            }
          },
          "gebruiksdoelen": [
            "woonfunctie"
          ],
          "oppervlakte": 43,
          "status": "Verblijfsobject in gebruik",
          "geconstateerd": "N",
          "documentdatum": "2021-07-01",
          "documentnummer": "D210972177",
          "voorkomen": {
            "tijdstipRegistratie": "2021-07-01T10:26:36.247",
            "versie": 2,
            "beginGeldigheid": "2021-07-01",
            "tijdstipRegistratieLV": "2021-07-01T10:48:29.003"
          },
          "maaktDeelUitVan": [
            "0268100000021458"
          ],
          "_links": {
            "self": {
              "href": "https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/verblijfsobjecten/0268010000036826"
            },
            "heeftAlsHoofdAdres": {
              "href": "https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/nummeraanduidingen/0268200000041560"
            },
            "maaktDeelUitVan": [
              {
                "href": "https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/panden/0268100000021458"
              }
            ]
          }
        }
      }
    ]
  }
}

Searching for addresses within a bounding box

The BAG API offers the possibility of requesting BAG data within a specific area (bounding box). It is possible, for example, to use a bounding box to search for addressable objects (with address data) within a maximum area of 250,000 square metres.

Within the adresseerbare objecten endpoint, the x and y coordinates of the bottom left corner and the x and y coordinates of the top right corner can be supplied. These two points make a rectangular box within which the search is carried out.

Note that Content-Crs epsg:28992 must be supplied with the query.

The URL is as follows:

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

{
  "_embedded": {
    "adresseerbareObjecten": [
      {
        "verblijfsobject": {
          "verblijfsobject": {
            "type": "Verblijfsobject",
            "heeftAlsHoofdAdres": "0014200010900021",
            "identificatie": "0014010011089620",
            "domein": "NL.IMBAG.Verblijfsobject",
            "geometrie": {
              "punt": {
                "type": "Point",
                "coordinates": [
                  230900.789,
                  582669.048,
                  0
                ]
              }
            },
            "gebruiksdoelen": [
              "overige gebruiksfunctie"
            ],
            "oppervlakte": 19,
            "status": "Verblijfsobject in gebruik",
            "geconstateerd": "N",
            "documentdatum": "2013-02-19",
            "documentnummer": "3535704",
            "voorkomen": {
              "tijdstipRegistratie": "2013-02-22T09:17:09",
              "versie": 2,
              "beginGeldigheid": "2013-02-19",
              "tijdstipRegistratieLV": "2013-02-22T09:35:31.531"
            },
            "maaktDeelUitVan": [
              "0014100010923600"
            ],
            "_links": {
              "self": {
                "href": "https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/verblijfsobjecten/0014010011089620"
              },
              "heeftAlsHoofdAdres": {
                "href": "https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/nummeraanduidingen/0014200010900021"
              },
              "maaktDeelUitVan": [
                {
                  "href": "https://api.bag.acceptatie.kadaster.nl/lvbag/individuelebevragingen/v2/panden/0014100010923600"
                }
              ]
            }
          }
        }
      }
    ]
  }
}

Restrictions on the use of the BAG API Individuele Bevragingen

Use of the BAG API Individuele Bevragingen is free of charge. Conditions apply to the use of this service in order to prevent excessive or undesirable use of the API. We want to keep the BAG API fast and usable for all consumers. To be able to guarantee this, limits have been set. More information about the restrictions of the BAG API can be found here.

Implement the API client

Client code can be generated with the “genereervariant” of the API specifications and a code generator. An overview of code generators can be found at OpenAPI.Tools.

Trying and testing the API

The behaviour of the API is easiest to test using Postman. You can import the openapi.yaml as a project, after which the various requests that this API supports are loaded.

API key

To be able to query the API, an API key is needed. You must include this in the request in the request header “X-Api-Key”. Request an API key for the BAG API.

Test cases

The tables below contain test cases for specific situations with which the behaviour of the API can be tested: