# Postcode App: Dutch address validation API and widget

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](https://www.pdok.nl/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`.

```bash
curl "https://api.cloud-captains.com/postcode/1234AB/56"
```

Response:

```json
{
  "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.

```html
<script src="https://app.cloud-captains.com/postcode/widget.js"></script>
<div data-cc-postcode data-target-straat="#street" data-target-plaats="#city"></div>
```

:::howto title="Add the widget to a form"
1. Add the `widget.js` `<script>` tag once, ideally just before the closing `</body>` tag.
2. Place the `<div data-cc-postcode>` element near your postal code and house number inputs.
3. Point `data-target-straat` and `data-target-plaats` at the CSS selectors of your street and city fields.
4. Test with a real combination such as `1234AB` and `56`, and confirm the street and city fields fill in automatically.
:::

:::tip title="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.
:::

:::warn title="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.

:::faq
### 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.
:::