# Postcode App: adresvalidatie en aanvullingen

Valideer Nederlandse adressen op postcode plus huisnummer en haal automatisch de straat, plaats, gemeente en provincie op. Zo voorkom je typefouten in bestellingen en formulieren, en hoeven bezoekers minder velden zelf in te vullen.

## Hoe het werkt

De Postcode App zoekt het adres op aan de hand van een postcode en huisnummer en geeft de bijbehorende adresgegevens terug. Je kunt kiezen uit twee manieren om dit in je eigen site of applicatie te gebruiken:

- De **JSON-API** voor maatwerk en server-side validatie.
- De **embed-widget** die je naast een bestaand adresformulier plaatst en die velden automatisch invult.

## Bron van de data

Wij gebruiken de [PDOK Locatieserver](https://www.pdok.nl/pdok-locatieserver) van het Kadaster. Dit is open en gratis overheidsdata met onder andere alle Nederlandse postcodes, straten en huisnummers. De onderliggende data wordt regelmatig bijgewerkt, dus nieuwe straten en adressen komen vanzelf mee.

## API gebruik

Roep de API aan met de postcode en het huisnummer in de URL.

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

De response bevat het volledige adres plus geo-coordinaten:

```json
{
  "postcode": "1234AB",
  "huisnummer": 56,
  "straat": "Voorbeeldstraat",
  "plaats": "Amsterdam",
  "gemeente": "Amsterdam",
  "provincie": "Noord-Holland",
  "geo": { "lat": 52.3676, "lng": 4.9041 }
}
```

De postcode mag met of zonder spatie. Een onbekende combinatie van postcode en huisnummer levert een lege of foutmelding-response op, zodat je in je formulier een duidelijke melding kunt tonen.

## Widget embed

Plaats het script eenmalig in je pagina en voeg het widget-element toe naast je adresformulier. Met de `data-target-*` attributen koppel je de uitkomst aan je eigen invoervelden.

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

Zodra een bezoeker een geldige postcode en huisnummer invult, vult de widget de gekoppelde velden voor straat en plaats automatisch in.

:::howto title="Widget koppelen aan je formulier"
1. Voeg het `<script>` van `widget.js` toe, het liefst net voor `</body>`.
2. Geef je velden voor straat en plaats een `id`, bijvoorbeeld `id="straat"` en `id="plaats"`.
3. Plaats het `<div data-cc-postcode>` element met de juiste `data-target-*` selectors.
4. Test met een bekend adres en controleer of de velden zich vullen.
:::

:::tip title="Houd je adresformulier kort"
Laat bezoekers alleen postcode en huisnummer typen en vul straat en plaats automatisch in. Dat scheelt invoerfouten en maakt je formulier merkbaar sneller. Toon de aangevulde velden wel zichtbaar, zodat mensen kunnen controleren dat het klopt.
:::

:::warn title="Valideer altijd ook aan de serverkant"
De widget verbetert de gebruikerservaring, maar is geen beveiliging. Controleer ingevoerde adressen ook via de API aan je serverkant voordat je ze opslaat of een bestelling verwerkt.
:::

:::faq
### Welke data zit achter de Postcode App?
De adresgegevens komen uit de PDOK Locatieserver van het Kadaster. Dat is open en gratis overheidsdata met alle Nederlandse postcodes, straten en huisnummers.

### Werkt de Postcode App ook voor Belgische adressen?
Nee, de dienst is gericht op Nederlandse adressen. De PDOK-data bevat alleen adressen binnen Nederland.

### Wat gebeurt er bij een onbekende postcode of huisnummer?
De API geeft een lege of foutmelding-response terug. In je formulier kun je dan een duidelijke melding tonen en de bezoeker vragen de invoer te controleren.

### Mag de postcode met een spatie worden ingevuld?
Ja, de invoer mag met of zonder spatie, bijvoorbeeld 1234 AB of 1234AB.

### Wat krijg ik precies terug per adres?
Je ontvangt straat, plaats, gemeente, provincie en geo-coordinaten (lat en lng), naast de ingevoerde postcode en het huisnummer.

### Moet ik de widget en de API allebei gebruiken?
Nee. De widget is handig voor snelle invoer in een formulier, de API voor maatwerk en validatie aan de serverkant. Voor een betrouwbare flow combineer je ze het liefst.
:::