API documentation

Geo Adrescheck Nationaal v2

Summary

Use this API to enrich your Dutch address data with geographical data.

Methods and endpoints

MethodEndpoint
POSThttps://api.postnl.nl/address/national/v2/geocode

Required input for API

FieldnameMandatory/optionalFormatExample
PostalCodeMandatoryString [6]1234AB
HouseNumberMandatoryString or Number [1-5]123 (only numerical values allowed)
HouseNumberAdditionOptionalString [6]A / a / a2


Or:

FieldnameMandatory/optionalFormatExample
City
MandatoryString [1-35]Amsterdam
StreetMandatoryString [1-95]Dam
HouseNumberMandatoryString or number [1-5]123 (only numerical values allowed)
HouseNumberAdditionOptionalString [6]A / a / a2

Expected output from API

FieldnameDescription of attributeFormat
CityCity of requested addressString
PostalCodePostalcode of requrested addressString [6]
StreetStreet of requested addressString
HouseNumberHousenumber of requested addressNumber
HouseNumberAdditionHousenumber addition of requested address if applicableString [6] or null
FormattedAddressFull formatted address according to PostNL standardArray with 2 strings
CoordinatesGeographic data represented in an arrayObject with 4 values
LatitudeLatitudinal value of locationNumber [8]
LatitudeLongitudinal value of locationNumber [8]
RdCoordinateXRijksdriehoek-coördinate on x-axisNumber [6]
RdCoordinateYRijksdriehoek-coördinate on y-axisNumber [6]
VierkantNetCodeXVierkantnet-coördinate on x-axisNumber [4]
VierkantNetCodeYVierkantnet-coördinate on y-axisNumber [4]

Possible error codes

Error codeError message
200JSON response with requested data. If address does not exist, you get an empty [] response.
4xxError on customer-side. Example: { "errors": [ { "status": "400", "title": "Bad Request", "detail": "PostalCode has the wrong format. It should be: 1234AB" } ] }
500Error on PostNL side

Example request & response

RequestResponse
{ "PostalCode": "1507TN", "City": "", "Street": "", "HouseNumber": "6", "HouseNumberAddition": "" }

[

{ "PostalCode": "1507TN", "HouseNumber": "6", "HouseNumberAddition": null, "Street": "Wals", "City": "ZAANDAM", "FormattedAddress": [ "Wals 6", "1507TN ZAANDAM" ], "Coordinates": { "Latitude": 52.439944, "Longitude": 4.806337, "RdCoordinateX": 115503, "RdCoordinateY": 494843, "VierkantNetCodeX": 1155, "VierkantNetCodeY": 4948 

]