--- updatedAt: 2026-10-08T17:38:18.000Z agentTools: projectIndex: https://docs.company.info/llms.txt --- # 📌 NL Locations # 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](https://docs.company.info/reference/get_nl-locations) *** ### Pagination Results are returned in pages of 10 by default. Use the `page` parameters to control this. | Parameter | Description | Default | Maximum | | -------------- | -------------------------- | ------- | ------- | | `page[size]` | Number of results per page | 10 | 20 | | `page[number]` | Page to retrieve | 1 | — | The response `meta` object always shows `totalResults` and `totalPages` so you know how many results exist in total. *** ### Common Search Parameters | Paramers | Type | Example | Notes | | :------------------- | :------ | :---------------------------- | :----------------------------- | | filter\[postalCode] | string | 1054KP | Exact Dutch postcode, no space | | filter\[houseNumber] | integer | 2 | Exact house number | | filter\[houseLetter] | string | A | Exact letter | | match\[street] | string | saxenburg | Fuzzy street search | | match\[city] | string | amsterdam | Fuzzy city search | | query | string | Saxenburgerstraat 2 Amsterdam | Minimum 2 characters | *** ### Example request Exact lookup by postal code, house number, and house letter: ```curl 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 ```json { "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](https://docs.company.info/reference/api-keys-1). | HTTP Status | When it occurs | What to do | | --------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------- | | `400 Bad Request` | Invalid parameter format (e.g. `filter[postalCode]=INVALID`) | Check your parameter values match the expected format | | `404 Not Found` | No address found matching the exact filters | Try relaxing the filter (e.g. remove `houseLetter`) or switch to `match[]` | | `500 Internal Server Error` | Unexpected server-side issue | Retry after a short delay; contact support if it persists | *** # Try it yourself! Ready to test? Head to our [API reference](https://docs.company.info/reference/get_nl-locations) 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`.