API documentation
Geo Adrescheck Nationaal v2
Summary
Use this API to enrich your Dutch address data with geographical data.
Methods and endpoints
| Method | Endpoint |
|---|---|
| POST | https://api.postnl.nl/address/national/v2/geocode |
Required headers
| Header key | Header value | Mandatory/optional |
|---|---|---|
| apikey | Your apikey | Mandatory |
| Content-Type | application/json | Mandatory |
Input parameters
| Fieldname | Mandatory/optional | Format | Example |
|---|---|---|---|
| PostalCode | Mandatory | String [6] | 1234AB |
| HouseNumber | Mandatory | String or Number [1-5] | 123 (only numerical values allowed) |
| HouseNumberAddition | Optional | String [6] | A / a / a2 |
Or:
| Fieldname | Mandatory/optional | Format | Example |
|---|---|---|---|
| City | Mandatory | String [1-35] | Amsterdam |
| Street | Mandatory | String [1-95] | Dam |
| HouseNumber | Mandatory | String or number [1-5] | 123 (only numerical values allowed) |
| HouseNumberAddition | Optional | String [6] | A / a / a2 |
Output parameters
| Fieldname | Description of attribute | Format |
|---|---|---|
| City | City of requested address | String |
| PostalCode | Postalcode of requrested address | String [6] |
| Street | Street of requested address | String |
| HouseNumber | Housenumber of requested address | Number |
| HouseNumberAddition | Housenumber addition of requested address if applicable | String [6] or null |
| FormattedAddress | Full formatted address according to PostNL standard | Array with 2 strings |
| Coordinates | Geographic data represented in an array | Object with 4 values |
| Latitude | Latitudinal value of location | Number [8] |
| Latitude | Longitudinal value of location | Number [8] |
| RdCoordinateX | Rijksdriehoek-coördinate on x-axis | Number [6] |
| RdCoordinateY | Rijksdriehoek-coördinate on y-axis | Number [6] |
| VierkantNetCodeX | Vierkantnet-coördinate on x-axis | Number [4] |
| VierkantNetCodeY | Vierkantnet-coördinate on y-axis | Number [4] |
Example request & response
| Request | Response |
|---|---|
| { "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 } } ] |
Possible error codes
| Error code | Error message |
|---|---|
| 200 | JSON response with requested data. If address does not exist, you get an empty [] response. |
| 4xx | Error on customer-side. Example: { "errors": [ { "status": "400", "title": "Bad Request", "detail": "PostalCode has the wrong format. It should be: 1234AB" } ] } |
| 500 | Error on PostNL side |