API

Address.matchExact

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.

Example REST request

Retrieving /addresses/exact/haarlem/julianastraat/30 with the proper authentication would use the following HTTP Request:

GET /rest/addresses/exact/haarlem/julianastraat/30 HTTP/1.1
Host: api.postcode.nl
Authorization: Basic 2eTpkU******…

Use URL encoding on the individual path elements, e.g. /addresses/exact/haarlem/grote%20houtstraat/1.

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.

Example response

This address exists, so we return a '200 OK' status in the headers, and json encoded data in the response body:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 410

{
  "street": "Julianastraat",
  "houseNumber": 30,
  "houseNumberAddition": "",
  "postcode": "2012ES",
  "city": "Haarlem",
  "municipality": "Haarlem",
  "province": "Noord-Holland",
  "rdX": 103242,
  "rdY": 487716,
  "latitude": 52.37487801,
  "longitude": 4.62714526,
  "bagNumberDesignationId": "0392200000029398",
  "bagAddressableObjectId": "0392010000029398",
  "addressType": "building",
  "purposes": [
	"office"
  ],
  "surfaceArea": 643,
  "houseNumberAdditions": [
	""
  ]
}

Returns

street:
string
Street name in accordance with "BAG (Basisregistraties 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.
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
Addition of the house number to uniquely define a location. These additions are officially recognized by the municipality. Null if addition not found (see houseNumberAdditions result field).
postcode:
string
Four number 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 "BAG (Basisregistraties adressen en gebouwen)". In capital and lowercase letters, including punctuation marks and accents. This field is at most 80 characters in length.
municipality:
string
Municipality name in accordance with "BAG (Basisregistraties 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".
province:
string
Official name of the province, correctly cased and with dashes where applicable.
rdX:
int
X coordinate according to Dutch Rijksdriehoeksmeting "(EPSG) 28992 Amersfoort / RD New". Values range from 0 to 300000 meters. Null for PO Boxes.
rdY:
int
Y coordinate according to Dutch Rijksdriehoeksmeting "(EPSG) 28992 Amersfoort / RD New". Values range from 300000 to 620000 meters. Null for PO Boxes.
latitude:
double
Latitude of address. Null for PO Boxes.
longitude:
double
Longitude of address. Null for PO Boxes.
bagNumberDesignationId:
string
Dutch term used in BAG: "nummeraanduiding id".
bagAddressableObjectId:
string
Dutch term used in BAG: "adresseerbaar object id". Unique identification for objects which have 'building', 'house boat site', or 'mobile home site' as addressType.
addressType:
string
Type of this address. See reference for possible values.
purposes:
array of strings
List of all purposes (Dutch: "gebruiksdoelen"). Null or an array of text values. See reference for possible values.
surfaceArea:
int
Surface in square meters. Null for PO Boxes.
houseNumberAdditions:
array of strings
List of all house number additions having the postcode and houseNumber which was input.

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.

Example REST request and response

Retrieving /addresses/exact/oostwold/polderweg/5 with the proper authentication would use the following HTTP Request:

GET /addresses/exact/oostwold/polderweg/5 HTTP/1.1
Host: api.postcode.nl
Authorization: Basic 2eTpkU******…

Will return a "409 Conflict" response

HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 181
{
    "exception": "City name is not unique, please specify one of `Oostwold gem. Leek, Oostwold gem. Oldambt`.",
    "exceptionId": "PostcodeNl_Service_PostcodeAddress_CityNotUniqueException"
}

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 5
9828PV Oostwold

The other address in the municipality Oldambt shares the same address, but has a different postcode:

Polderweg 5
9682XS Oostwold

This ambiguity can be resolved by adding a suffix to the city name.

Example REST request and response

Retrieving /addresses/exact/oostwold%20gem.%20leek/polderweg/5 with the proper authentication would use the following HTTP Request:

This address exists and is unique, so we return a '200 OK' status in the headers, and json encoded data in the response body:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 401

{
  "street": "Polderweg",
  "houseNumber": 5,
  "houseNumberAddition": "",
  "postcode": "9828PV",
  "city": "Oostwold",
  "municipality": "Leek",
  "province": "Groningen",
  "rdX": 225654,
  "rdY": 579899,
  "latitude": 53.2010708,
  "longitude": 6.44454442,
  "bagNumberDesignationId": "0022200000006277",
  "bagAddressableObjectId": "0022010000006277",
  "addressType": "building",
  "purposes": [
	"residency"
  ],
  "surfaceArea": 205,
  "houseNumberAdditions": [
	""
  ]
}

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