API Documentatie

Introductie

De Nederlandse Postcode API biedt toegang tot betrouwbare adresgegevens op basis van Nederlandse postcodes. Alle endpoints zijn GET requests en retourneren JSON.

Base URL

https://api.nederlandpostcode.nl/

Authenticatie

Alle requests vereisen authenticatie via een Bearer token in de Authorization-header.

Authorization: Bearer npa_live_xxx

Alle tokens beginnen met een prefix die de omgeving aangeeft:

• npa_live_ voor productie tokens
• npa_test_ voor test tokens

Met een testtoken kan je de API gratis uitproberen. De testtokens werken alleen voor de volgende postcodes:

• 1015CNKeizersgracht, Amsterdam (10 adressen)
• 1118BNSchiphol Boulevard, Schiphol (3 adressen)

Met een account kan je meerdere projecten beheren, elk met hun eigen test- en productietokens.

Endpoints

Hieronder vind je een overzicht van de beschikbare endpoints van de Nederlandse Postcode API. Alle endpoints vereisen authenticatie met een Bearer token.

Klik op een endpoint hieronder voor meer details en voorbeeld requests/responses:

• GET /v1/address
• GET /v1/coordinates
• GET /v1/energy-label
• GET /quota

GET /v1/address

Dit endpoint haalt adressen op aan de hand van een opgegeven postcode en huisnummer, met een optionele huisnummertoevoeging. Dit kan handig zijn voor het valideren van adressen of het verkrijgen van aanvullende adresinformatie. Het resultaat is altijd een lijst van adressen die voldoen aan de opgegeven criteria, ook als er maar één adres wordt gevonden.

Query parameters

Opmerking: De parameter attributes[] kan worden gebruikt om aanvullende informatie op te vragen.

Opmerking: Indien parameter addition wordt weggelaten, worden alle adressen voor het opgegeven postcode en huisnummer geretourneerd. Als de parameter wel wordt meegegeven, maar leeg is - wordt er gezocht naar adressen zonder toevoeging.

Ondersteunde extra velden

De volgende extra velden kunnen worden opgevraagd via de attributes[] parameter:

Voorbeeld met enkel adres

Dit voorbeeld haalt het adres op voor postcode 1118BN en huisnummer 800 met coördinaten en wijknaam. Er is maar één adres voor deze combinatie.

GET https://api.nederlandpostcode.nl/v1/address?postcode=1118BN&number=800&attributes[]=coordinates&attributes[]=district&attributes[]=function

{
    "data": [
        {
            "postcode": "1118BN",
            "number": 800,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "municipality": "Haarlemmermeer",
            "province": "Noord-Holland",
            "country": "Nederland",
            "details": {
                "district": {
                    "official": "Schiphol",
                    "name": "Schiphol"
                },
                function": "kantoorfunctie"
            }
            "coordinates": {
                "latitude": 52.30528553688755,
                "longitude": 4.750645160863609
            }
        }
    ]
}

Voorbeeld met meerdere adressen

Dit voorbeeld haalt het adres op voor postcode 1015CN en huisnummer 10. Er bestaan 4 adressen voor deze combinatie.

GET https://api.nederlandpostcode.nl/v1/address?postcode=1015CN&number=10

{
    "data": [
        {
            "postcode": "1015CN",
            "number": 10,
            "addition": "A",
            "street": "Keizersgracht",
            "city": "Amsterdam",
            "municipality": "Amsterdam",
            "province": "Noord-Holland",
            "country": "Nederland"
        },
        {
            "postcode": "1015CN",
            "number": 10,
            "addition": "B",
            "street": "Keizersgracht",
            "city": "Amsterdam",
            "municipality": "Amsterdam",
            "province": "Noord-Holland",
            "country": "Nederland"
        },
        {
            "postcode": "1015CN",
            "number": 10,
            "addition": "C",
            "street": "Keizersgracht",
            "city": "Amsterdam",
            "municipality": "Amsterdam",
            "province": "Noord-Holland",
            "country": "Nederland"
        },
        {
            "postcode": "1015CN",
            "number": 10,
            "addition": "D",
            "street": "Keizersgracht",
            "city": "Amsterdam",
            "municipality": "Amsterdam",
            "province": "Noord-Holland",
            "country": "Nederland"
        }
    ]
}

Voorbeeld met geen adres

Dit voorbeeld haalt het adres op voor postcode 1234AB en huisnummer 9999. Er bestaat geen adres voor deze combinatie. Het response bevat een lege lijst met de 200 OK statuscode.

GET https://api.nederlandpostcode.nl/v1/address?postcode=1234AB&number=9999

{
    "data": []
}

GET /v1/coordinates

Dit endpoint haalt adressen op op basis van opgegeven coördinaten (latitude en longitude). Dit kan handig zijn voor het vinden van adressen in de buurt van een specifieke locatie. Dit endpoint retourneert net als het adres-endpoint een array van adressen, maar dan gesorteerd op afstand tot de opgegeven coördinaten.

Dit endpoint geeft altijd de coördinaten terug van het gevonden adres. Andere velden zoals district zijn niet beschikbaar via dit endpoint.

Query parameters

Voorbeeld met gevonden locatie

Dit voorbeeld haalt het dichtstbijzijnde adres op voor de opgegeven coördinaten (latitude: 52.305285, longitude: 4.750645).

GET https://api.nederlandpostcode.nl/v1/coordinates?latitude=52.305285&longitude=4.750645&limit=1

{
    "data": [
        {
            "postcode": "1118BN",
            "number": 800,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "municipality": "Haarlemmermeer",
            "province": "Noord-Holland",
            "country": "Nederland",
            "coordinates": {
                "latitude": 52.30528553688755,
                "longitude": 4.750645160863609
            },
        }
    ]
}

Voorbeeld met geen gevonden locatie

Als er geen adres dichtbij de opgegeven coördinaten kan worden gevonden, geeft het endpoint een 422 Unprocessable Content statuscode terug met een foutmelding.

GET https://api.nederlandpostcode.nl/v1/coordinates?latitude=0&longitude=0

{
    "message": "No address found near the provided coordinates."
}

GET /v1/energy-label

Dit endpoint haalt de huidige en historische energielabels op voor een gegeven adres.

Query parameters

Voorbeeld met enkel adres

Dit voorbeeld haalt het adres op voor postcode 1118BN en huisnummer 800.

GET https://api.nederlandpostcode.nl/v1/energy-label?postcode=1118BN&number=800

{
    "data": [
        {
            "postcode": "1118BN",
            "number": 800,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "energy_labels": [
                {
                    "inspection_date": "02-08-2022",
                    "valid_until_date": "02-08-2032",
                    "construction_type": "utiliteitsbouw",
                    "building_type": null,
                    "energy_label": "A+++",
                    "max_energy_demand": 98.4,
                    "max_fossil_energy_demand": 55.48,
                    "min_renewable_share": 55.3
                }
            ]
        }
    ]
}

Voorbeeld met geen of meerdere adressen

Als je een energielabel ophaalt voor een niet-bestaand adres, of voor een postcode-huisnummercombinatie die meerdere adressen oplevert, krijg je een foutmelding met statuscode 422 Unprocessable Content.

{
    "message": "No address found for the given postcode and number."
}

{
    "message": "Multiple addresses found for the given postcode and number."
}

Voor meer informatie over de inhoud van de verschillende velden bekijk de Energielabel API pagina.

GET /quota

Dit endpoint haalt het huidige API-verbruik en de limieten op voor de geauthenticeerde gebruiker. Dit kan handig zijn om te monitoren hoeveel requests er nog beschikbaar voor de huidige periode.

Let op: dit endpoint heeft geen versienummer in de URL.

Het kan tot 5 minuten duren voordat het verbruik up-to-date is.

Voorbeeld quota

Dit voorbeeld toont het huidige API-verbruik en de limieten voor de geauthenticeerde gebruiker.

GET https://api.nederlandpostcode.nl/quota

{
    "data": {
        "quota": {
            "used": 250,
            "limit": 2000
        }
    }
}

Statuscodes en foutafhandeling

De API gebruikt standaard HTTP-statuscodes om de uitkomst van een request aan te geven. Hieronder staat een overzicht van de meest voorkomende statuscodes en hun betekenis.

Voorbeeld van een validatiefout

Dit voorbeeld toont een response wanneer verplichte velden ontbreken in de aanvraag. In dit geval ontbreken de velden postcode en number.

{
    "message": "The postcode field is required. (and 1 more error)",
    "errors": {
        "postcode": [
            "The postcode field is required."
        ],
        "number": [
            "The number field is required."
        ]
    }
}

Rate Limiting

Om misbruik van de API te voorkomen, is er een rate limiting beleid van kracht. Elke API-token heeft een limiet op het aantal requests dat binnen een bepaalde tijdsperiode mag worden gedaan. Als deze limiet wordt overschreden, zal de API een 429 Too Many Requests-statuscode retourneren.

Er is een standaard limiet per token om overbelasting van de server te voorkomen en je token te beschermen tegen onbedoeld hoog verbruik. Neem contact op met ons supportteam als je een hogere limiet nodig hebt voor jouw gebruiksscenario.

Er is ook een maandelijkse quota op het totale aantal requests, afhankelijk van je abonnement. Je kan je huidige verbruik inzien en je limieten verhogen door in te loggen op je account dashboard.

Voorbeeld overschrijding per minuut

Dit voorbeeld toont een response wanneer de rate limit per minuut is overschreden. In dit geval is de limiet ingesteld op 60 requests per minuut.

{
    "message": "Rate limit exceeded.",
    "quota": {
        "strategy": "per_minute",
        "limit": 60
    }
}

Voorbeeld overschrijding maandelijkse limiet

Dit voorbeeld toont een response wanneer de maandelijkse API quota is overschreden. In dit geval is de limiet ingesteld op 2000 requests per maand.

{
    "message": "Monthly API quota exceeded.",
    "quota": {
        "strategy": "per_month",
        "limit": 2000
    }
}

Plugins

We bieden verschillende plugins om de Nederlandse Postcode API eenvoudig te integreren in populaire platforms en frameworks.

Heb je zelf een plugin ontwikkeld? Neem dan contact met ons op, zodat we deze hier kunnen vermelden.