Validate Dutch addresses by postal code plus house number and auto-fill the street and city for the person filling in your form.
Data source
We use the PDOK Locatieserver, the free and open geocoding service from the Dutch Land Registry (Kadaster). This is open data and the source of truth for Dutch addresses. Because the data comes straight from Kadaster, a postal code plus house number resolves to exactly one official address.
API usage
Call the API with a postal code and house number in the path. The postal code accepts both 1234AB and 1234 AB.
curl "https://api.cloud-captains.com/postcode/1234AB/56"
Response:
{
"postcode": "1234AB",
"huisnummer": 56,
"straat": "Voorbeeldstraat",
"plaats": "Amsterdam",
"gemeente": "Amsterdam",
"provincie": "Noord-Holland",
"geo": { "lat": 52.3676, "lng": 4.9041 }
}
When no address matches the combination, the API returns HTTP 404 with an empty body, so you can show a clear validation error in your form.
Widget embed
The widget is the fastest way to add validation without writing any request code yourself. Add the script once, then drop the element next to your address form.
<script src="https://app.cloud-captains.com/postcode/widget.js"></script>
<div data-cc-postcode data-target-straat="#street" data-target-plaats="#city"></div>
Add the widget to a form
- Add the
widget.js<script>tag once, ideally just before the closing</body>tag. - Place the
<div data-cc-postcode>element near your postal code and house number inputs. - Point
data-target-straatanddata-target-plaatsat the CSS selectors of your street and city fields. - Test with a real combination such as
1234ABand56, and confirm the street and city fields fill in automatically.
Bind the widget to your own fields
Drop the widget next to your address form and bind it to input fields with data-target-* attributes. Validation auto-fills the matching fields, so your visitor only types the postal code and house number.
Keep house numbers separate
Pass the house number as its own value, not glued to the postal code. House-number additions such as 12-A belong in a separate field so the lookup stays accurate.
Limits and reliability
There are no rate limits for Cloud Captains customers. The service mirrors PDOK open data, so availability and accuracy follow the official Kadaster source.
Which addresses does the Postcode App cover?
It covers addresses in the Netherlands only, because it is built on the Dutch PDOK Locatieserver. For addresses outside the Netherlands you need a different service.
Is the postal code case sensitive?
No. Both uppercase and lowercase work, and a space between the digits and letters is allowed, so 1234ab and 1234 AB resolve to the same address.
What happens when an address does not exist?
The API returns HTTP 404 with an empty body. The widget shows no auto-fill, which lets you flag the combination as invalid in your form.
Do I need a PDOK account or API key?
No. The Postcode App handles the connection to PDOK for you, so you only call the Cloud Captains API or embed the widget.
Are there any usage limits?
There are no rate limits for Cloud Captains customers. Availability follows the underlying PDOK open-data service.