Address lookup by city, street and housenumber
Get an address based on its unique combination of city, street, house number and house number addition.
Coordinate and surfaceArea values are null values if no location is known, i.e. if the address is a PO Box.
You must always check the houseNumberAddition result field, as a successful response is also returned if only the input addition isn't found.
URL template
The REST API requires GET requests. Parameters are added to the REST resource URL, and each parameter must be URL-encoded:
https://api.postcode.eu
Example REST request
Retrieving /nl/v1/addresses/exact/haarlem/julianastraat/30 with the proper authentication would use the following HTTP Request:
GET /nl/v1/addresses/exact/haarlem/julianastraat/30 HTTP/1.1 Host: api.postcode.eu Authorization: Basic 2eTpkU******…
Use URL encoding on the individual path elements, e.g. /addresses/exact/haarlem/grote%20houtstraat/1.
Example response
The lookup is successful so we receive a 200 OK status in the headers:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8
And a JSON response in the body:
{ "street": "Julianastraat", "streetNen": "Julianastraat", "houseNumber": 30, "houseNumberAddition": "", "postcode": "2012ES", "city": "Haarlem", "cityShort": "Haarlem", "cityId": "2907", "municipality": "Haarlem", "municipalityShort": "Haarlem", "municipalityId": "0392", "province": "Noord-Holland", "rdX": 103242, "rdY": 487716, "latitude": 52.37487801, "longitude": 4.62714526, "bagNumberDesignationId": "0392200000029398", "bagAddressableObjectId": "0392010000029398", "addressType": "building", "purposes": [ "office" ], "surfaceArea": 643, "houseNumberAdditions": [ "" ] }
Parameters
-
city:
string
-
City name in capital and lowercase letters, including punctuation marks and accents. A province ("NH") or municipality suffix ('gem. Woerden') may be added to identify a non-unique city name. Matched ignoring case and diacritics.
-
street:
string
-
Street name in capital or lowercase letters, including punctuation marks and accents. Specify "Postbus" for a PO box. Matched ignoring case and diacritics.
-
houseNumber:
int
-
House number, within a range of 1 to 99999.
-
houseNumberAddition:
string
-
Addition to the house number, required to uniquely define an address with multiple additions. The longest valid addition is 6 characters.
Returns
-
street:
string
-
Street name in accordance with the BAG Registry (Dutch: BAG - Basisregistratie Adressen en Gebouwen). In capital and lowercase letters, including punctuation marks and accents. This field is at most 80 characters in length. Filled with "Postbus" in case it is a range of PO boxes.
-
streetNen:
string
-
Street name in NEN-5825 notation, which has a lower maximum length. In capital and lowercase letters, including punctuation marks and accents. This field is at most 24 characters in length. Filled with "Postbus" in case it is a range of PO boxes.
-
houseNumber:
int
-
House number of a perceel. In case of a Postbus match the house number will always be 0. Range: 0-99999
-
houseNumberAddition:
string or null
-
Addition of the house number to uniquely define a location. These additions are officially recognized by the municipality. This field is at most 6 characters in length and null if the given addition was not found (see houseNumberAdditions result field). The addition "" is returned for an address without an addition.
-
postcode:
string
-
Four digit neighborhood code (first part of a postcode). Range: 1000-9999 plus two character letter combination (second part of a postcode). Range: "AA"-"ZZ"
-
city:
string
-
Official city name in accordance with the BAG Registry (Dutch: BAG - Basisregistratie Adressen en Gebouwen). In capital and lowercase letters, including punctuation marks and accents. This field is at most 80 characters in length.
-
cityShort:
string
-
City name, shortened to fit a lower maximum length. In capital and lowercase letters, including punctuation marks and accents. This field is at most 24 characters in length.
-
cityId:
string
-
Unique identifier for the city (Dutch: "woonplaatscode") as defined by the BAG Registry (Dutch: BAG - Basisregistratie Adressen en Gebouwen). Range "0000"-"9999"
-
municipality:
string
-
Municipality name in accordance with the BAG Registry (Dutch: BAG - Basisregistratie Adressen en Gebouwen). In capital and lowercase letters, including punctuation marks and accents. This field is at most 80 characters in length. Examples: "Baarle-Nassau", "'s-Gravenhage", "Haarlemmerliede en Spaarnwoude".
-
municipalityShort:
string
-
Municipality name, shortened to fit a lower maximum length. In capital and lowercase letters, including punctuation marks and accents. This field is at most 24 characters in length. Examples: "Baarle-Nassau", "'s-Gravenhage", "Haarlemmerliede c.a.".
-
municipalityId:
string
-
Unique identifier for the municipality (Dutch: "gemeentecode") as defined by the National Office for Identity Data (Dutch: Rijksdienst voor Indentiteitsgegevens (RvIG)). Range "0000"-"9999"
-
province:
string
-
Official name of the province, correctly cased and with dashes where applicable.
-
rdX:
int or null
-
X coordinate according to Dutch Coordinate system "(EPSG) 28992 Amersfoort / RD New" (Dutch: Rijksdriehoeksmeting). Values range from 0 to 300000 meters. Null for PO Boxes.
-
rdY:
int or null
-
Y coordinate according to Dutch Coordinate system "(EPSG) 28992 Amersfoort / RD New" (Dutch: Rijksdriehoeksmeting). Values range from 300000 to 620000 meters. Null for PO Boxes.
-
latitude:
double or null
-
Latitude of address. Null for PO Boxes.
-
longitude:
double or null
-
Longitude of address. Null for PO Boxes.
-
bagNumberDesignationId:
string or null
-
Unique identifier for address designation. (Dutch: nummeraanduiding id)
-
bagAddressableObjectId:
string or null
-
Unique identifier for addressable object designation (Dutch: adresseerbaar object id). If null no active object is currently registered.
-
addressType:
string
-
Type of this address. See reference for possible values.
-
purposes:
string[] or null
-
List of all purposes (Dutch: gebruiksdoelen). Null or an array of text values. See reference for possible values.
-
surfaceArea:
int or null
-
Surface in square meters. Null for PO Boxes.
-
houseNumberAdditions:
string[]
-
List of all house number additions having the postcode and houseNumber which was input. The addition "" is returned for an address without an addition.
References
Name matching
The street and city variables passed to the Address.matchExact method must match the official name, but there are two character properties which are ignored:
- Case: The characters 'A', 'a', etc., will match each other.
- Diacritics: The characters 'e', 'é', 'ë', 'É', etc., will match each other.
For example, all of the following street names will match the official name:
- Official name
- Prévinairestraat
- No diatritics
- Previnairestraat
- All lower case
- previnairestraat
- Different case
- PrÉvinairestraat
- Different diatritic
- Prëvinairestraat
- Extra diacritics
- Prévinairèstraat
- Extra capitalization
- PrévinaireSTRAAT
Only the official name is returned in the response.
Unique addresses
The Address.matchExact method uses the combination of city, street, house number and addition to uniquely identify an address. However, there are a few cities in the Netherlands which have the same name. Some of these cities have the same streets and house numbers.
There are about 300 of these addresses (out of 9 million). These addresses require you to add a suffix to the city name to match the intended address without ambiguity.
The json-rest API will return a special "409 Conflict" status code when such an address is requested.
Example of a non-unique address
The city Oostwold exists in two different municipalities, one in the municipality Leek:
Polderweg 59828PV Oostwold
The other address in the municipality Oldambt shares the same address, but has a different postcode:
Polderweg 59682XS Oostwold
This ambiguity can be resolved by adding a suffix to the city name.
City Suffixes
City names may be suffixed by either a municipality name or province code:
- municipality name: "Oostwold gem. Leek"
- province code: "Geesteren GLD"
These suffixes must be added to a non-unique city name in a non-unique address, but may also be added to an already unique city name.
Municipality suffixes
Any valid municipality may be added to the city in the form of "[city name] gem. [municipality name]":
- Amsterdam gem. Amsterdam
- Oostwold gem. Leek
- Haarlemmerliede gem. Haarlemmerliede en Spaarnwoude
Province suffixes
Any valid province suffix may be added to the city in the form of "[city name] [province suffix]":
- Geesteren GLD
- Amsterdam NH
- Maastricht LB
The complete list of province suffixes:
- DR
- Drenthe
- FL
- Flevoland
- FR
- Friesland
- GLD
- Gelderland
- GN
- Groningen
- LB
- Limburg
- NB
- Noord-Brabant
- NH
- Noord-Holland
- OV
- Overijssel
- UT
- Utrecht
- ZLD
- Zeeland
- ZH
- Zuid-Holland