API-documentatie — AdresPostcode.nl

Overzicht

Basis-URL voor alle API-verzoeken:

https://adrespostcode.nl/v1

Er zijn twee endpoints beschikbaar:

Postcode → adres — haal volledige adresgegevens op met postcode en huisnummer
Adres → postcode — zoek postcodes op straatnaam en plaats

Authenticatie

Stuur bij elk verzoek je API-sleutel mee in de HTTP-header:

X-API-Key: ap_jouw_sleutel_hier

Alternatief (niet aanbevolen): queryparameter api_key.

Elke sleutel is gekoppeld aan één IP-adres of hostname. Verzoeken vanaf een andere herkomst worden geweigerd (HTTP 403). Stel je IP/hostname in via het dashboard.

Vraag een gratis API-sleutel aan — 10 calls per maand, geen creditcard.

Postcode → adres

GET /v1/adres

Haal adresgegevens op basis van postcode en huisnummer.

Parameters

Parameter	Verplicht	Beschrijving
`postcode`	Ja	Nederlandse postcode, bijv. `1012KX` of `1012 KX`
`nr`	Ja	Huisnummer (geheel getal)
`toevoeging`	Nee	Huisnummertoevoeging, bijv. `A` of `bis`

Voorbeeldverzoek

GET https://adrespostcode.nl/v1/adres?postcode=1012KX&nr=1

X-API-Key: ap_jouw_sleutel

Response (200)

{
  "postcode": "1012 KX",
  "straat": "Dam",
  "huisnummer": 1,
  "toevoeging": null,
  "stad": "Amsterdam",
  "gemeente": "Amsterdam",
  "provincie": "Noord-Holland",
  "lat": 52.3728,
  "lon": 4.8936
}

Adres → postcode

GET /v1/postcode

Zoek adressen en postcodes op straatnaam en plaats. Retourneert maximaal 10 resultaten.

Parameters

Parameter	Verplicht	Beschrijving
`straat`	Ja	Straatnaam, bijv. `Dam`
`stad`	Ja	Plaatsnaam, bijv. `Amsterdam`

Voorbeeldverzoek

GET https://adrespostcode.nl/v1/postcode?straat=Dam&stad=Amsterdam

X-API-Key: ap_jouw_sleutel

Response (200)

{
  "resultaten": [
    {
      "postcode": "1012 JS",
      "straat": "Dam",
      "huisnummer": 1,
      "toevoeging": null,
      "stad": "Amsterdam",
      "gemeente": "Amsterdam",
      "provincie": "Noord-Holland",
      "lat": 52.3728,
      "lon": 4.8936
    }
  ]
}

Foutcodes

Bij een fout retourneert de API JSON met een error-veld:

Code	Betekenis	Voorbeeld
`400`	Ontbrekende of ongeldige parameters	`{"error": "Parameters postcode en nr zijn verplicht."}`
`401`	Geen of ongeldige API-sleutel	`{"error": "Ongeldige API-sleutel."}`
`403`	Verzoek van niet-geautoriseerd IP/hostname	`{"error": "Verzoek komt niet van het geautoriseerde IP of hostname."}`
`404`	Geen resultaat gevonden	`{"error": "Adres niet gevonden."}`
`429`	Maandlimiet bereikt	`{"error": "Maandelijkse API-limiet bereikt.", "limiet": 1000}`

Limieten

Elk abonnement heeft een maandelijks maximum aan API-calls. Je huidige verbruik zie je in het dashboard.

Bij betaalde plannen ontvang je een e-mail bij 50%, 75% en 90% van je limiet. Bekijk alle tarieven.

Codevoorbeelden

                        // JavaScript / fetch

                        const res = await fetch(

                          'https://adrespostcode.nl/v1/adres?postcode=1012KX&nr=1',

                          { headers: { 'X-API-Key': 'ap_jouw_sleutel' } }

                        );

                        const adres = await res.json();

                        console.log(adres.straat, adres.stad);