Address lookup by postcode and house number

Get an address based on its unique combination of postcode, 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/nl/v1/addresses/postcode/{postcode}/{houseNumber}/{houseNumberAddition}

Example REST request

Retrieving /nl/v1/addresses/postcode/2012ES/30/ with the proper authentication would use the following HTTP Request:

GET /nl/v1/addresses/postcode/2012ES/30/ HTTP/1.1
Host: api.postcode.eu
Authorization: Basic 2eTpkU******…

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

postcode: string

Four digit neighborhood code plus two character letter combination

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