Purpose of the API

The NL Locations API lets you search for Dutch addresses using a variety of parameters. It returns a list of addresses ranked by best match, enriched with BAG (Basisregistratie Adressen en Gebouwen) data including geolocation, building details, and official address identifiers.

How to use?

Base URL

https://api.company.info/

GET /nl/locations

Search for a Dutch address using one or more search parameters. Returns a paginated list of matching addresses with their full details.

Search modes

The API offers three ways to search, which can be combined:

filter — Exact match

Returns results only when the input matches 100%. If the value is slightly off, no results are returned. Use this when you have clean, validated input data.

/nl/locations?filter[postalCode]=1054KP&filter[houseNumber]=2&filter[houseLetter]=A

match — Fuzzy match

Searches with the given parameters and returns results based on the highest score. Tolerates partial input and minor variations. Use this for search-as-you-type or when input may be incomplete.

/nl/locations?match[street]=saxenburg&match[city]=amsterdam

query — Free-text search

Pass a single string and the API searches across all fields simultaneously. Best for open search boxes where you don't know which field the user is filling in. Minimum 2 characters.

/nl/locations?query=Saxenburgerstraat 2 Amsterdam

📘

All available search parameters are listed in our API reference

Pagination

Results are returned in pages of 10 by default. Use the page parameters to control this.

The response meta object always shows totalResults and totalPages so you know how many results exist in total.

Common Search Parameters

Example request

Exact lookup by postal code, house number, and house letter:

curl --request GET \
     --url 'https://api.company.info/nl/locations?filter[postalCode]=1054KP&filter[houseNumber]=2&filter[houseLetter]=A&page[size]=10&page[number]=1' \
     --header 'X-API-KEY: *********************' \
     --header 'accept: application/vnd.api+json'

Example response

{
    "data": [
        {
            "type": "locations",
            "id": "363200013047546",
            "attributes": {
                "street": "Saxenburgerstraat",
                "houseNumber": 2,
                "houseLetter": "A",
                "houseNumberAddition": "3",
                "postalCode": "1054KP",
                "city": "Amsterdam",
                "municipality": "Amsterdam",
                "province": "Noord-Holland",
                "lat": 52.3701,
                "lon": 4.8952,
                "x": 119131.534,
                "y": 485790.249,
                "objectID": 363010012587396,
                "numberIndication": 363200013047546,
                "buildingID": 363100012077044,
                "buildingStatus": "PAND_IN_GEBRUIK",
                "buildingYear": 1881,
                "status": "VERBLIJFSOBJECT_GEVORMD",
                "surfaceArea": 98,
                "usagePurpose": "woonfunctie",
                "secondaryAddress": false
            }
        }
    ],
    "links": {
        "self": "/nl/locations?filter[postalCode]=1054KP&filter[houseNumber]=2&filter[houseLetter]=A&page[size]=10&page[number]=1",
        "next": "/nl/locations?filter[postalCode]=1054KP&filter[houseNumber]=2&filter[houseLetter]=A&page[size]=10&page[number]=2",
        "last": "/nl/locations?filter[postalCode]=1054KP&filter[houseNumber]=2&filter[houseLetter]=A&page[size]=10&page[number]=1"
    },
    "meta": {
        "totalPages": 1,
        "totalResults": 1
    }
}

⚠️ Possible errors

This list does not include errors related to API key issues. For those, see API key errors.

Try it yourself!

Ready to test? Head to our API reference page where you can run live requests directly in your browser.

Glossary

BAG (Basisregistratie Adressen en Gebouwen) The official Dutch government registry of all addresses and buildings in the Netherlands. All address data in this API is sourced from BAG and linked via BAG identifiers.

objectID The BAG Addressable Object Identifier (AOID). Uniquely identifies a specific dwelling, unit, or space (verblijfsobject) within a building.

numberIndication The BAG Number Indication Identifier (NIID). Identifies the specific house number designation as registered in BAG.

buildingID The BAG identifier for the building (pand) as a whole — as opposed to the individual unit inside it.

houseNumber The numeric part of a Dutch address (e.g. 12).

houseLetter A single letter directly following the house number (e.g. A in Kalverstraat 12A), assigned by the municipality to distinguish units within the same building. Officially registered in BAG.

houseNumberAddition An additional code after the house number (and optional letter) to further identify a specific unit (e.g. bis, hoog, II, or 3). Also officially registered in BAG. Can appear with or without a houseLetter.

💡

Example: Saxenburgerstraat 2A-3 means houseNumber = 2, houseLetter = A, houseNumberAddition = 3. All three components can exist on the same address.

postalCode Dutch postcode in 1234AB format — 4 digits followed by 2 uppercase letters, no space.

status The BAG status of the address object (verblijfsobject). Common values: VERBLIJFSOBJECT_IN_GEBRUIK (in use), VERBLIJFSOBJECT_GEVORMD (formed/registered but not yet in use).

buildingStatus The BAG status of the building (pand). Common value: PAND_IN_GEBRUIK (building in use).

usagePurpose The official intended use of the address object according to BAG (gebruiksfunctie). Examples: woonfunctie (residential), kantoorfunctie (office), overige gebruiksfunctie (other).

secondaryAddress A boolean indicating whether this is a secondary address (nevenadres) rather than the primary address for this object.

x / y Coordinates in the Dutch RD (Rijksdriehoeksmeting) coordinate system. Used in Dutch national mapping applications. These are distinct from lat/lon (WGS-84).

FAQ

Can I search by street name only? Yes, use match[street]=kalverstraat. Note that filter[street] requires an exact match, so match[] is preferred for street-based searches.

What is the difference between filter and match? filter returns results only on a 100% exact match — if anything is off, you get zero results. match is fuzzy and returns the closest results ranked by score. For validated data (e.g., a known postcode and house number), use filter. For user input or partial data use match.

Can I combine filter and match in the same request? Yes. For example, you can use filter[postalCode]=1054KP for an exact postcode match combined with match[houseNumber]=2 for a fuzzy house number match.

Why do some addresses have both a houseLetter and a houseNumberAddition? In the Netherlands, a single address can officially have all three components. For example Saxenburgerstraat 2A-3 means houseNumber 2, houseLetter A, houseNumberAddition 3. This is common in older buildings in cities like Amsterdam, where subdivisions happened over multiple phases.

What do lat: 0 and lon: 0 mean in the response? This means coordinates are not yet available for that specific address. Not all BAG records have geolocation data. When this occurs, use the x and y RD coordinates if available, or look up coordinates separately.

How do I get more than 10 results? Set page[size] up to a maximum of 20, or use page[number] to retrieve subsequent pages. The meta.totalResults and meta.totalPages fields tell you how many results exist in total.

What is the difference between objectID and buildingID? objectID identifies a specific unit or dwelling (verblijfsobject) — for example, one apartment in a building. buildingID identifies the physical building (pand) as a whole. Multiple objectID values can share the same buildingID.