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 met je API-key. Stuur deze mee als Bearer token in de Authorization-header.

Authorization: Bearer npa_live_xxx

Alle API-keys beginnen met een prefix die de omgeving aangeeft:

• npa_live_ voor live API-keys
• npa_test_ voor test API-keys

Met een account kun je meerdere projecten beheren, elk met hun eigen test en live API-keys.

Test postcodes

Met een test API-key (npa_test_) kun je alle endpoints gratis uitproberen. Je krijgt dezelfde responses als met een live API-key, maar alleen voor postcodes die beginnen met 1012, 1015 of 1118, met elke lettercombinatie. Testverzoeken tellen niet mee voor je maandelijkse quota; een test API-key heeft wel een limiet van 100 verzoeken per dag.

Wil je direct aan de slag? Gebruik dan een van deze adressen:

Gebruik je een test API-key met een andere postcode, dan krijg je een 403 Forbidden. Bij de range-endpoints geldt dit voor het opgegeven referentieadres, bij /v1/coordinates voor het dichtstbijzijnde adres en bij /v1/energy-label-radius voor het dichtstbijzijnde adres met een energielabel binnen de straal.

{
    "message": "Test API-keys are limited to postcodes starting with 1012, 1015 or 1118. Use a live API-key to access all addresses."
}

Direct uitproberen

Kopieer een van deze verzoeken en stuur je test API-key mee in de Authorization-header:

GET https://api.nederlandpostcode.nl/v1/address?postcode=1015CN&number=10
GET https://api.nederlandpostcode.nl/v1/address-range?postcode=1118BN&number=800&start_number=700&end_number=900
GET https://api.nederlandpostcode.nl/v1/coordinates?latitude=52.305285&longitude=4.750645
GET https://api.nederlandpostcode.nl/v2/energy-label?postcode=1012PS&number=20
GET https://api.nederlandpostcode.nl/v1/energy-label-range?postcode=1118BN&number=800&start_number=700&end_number=900
GET https://api.nederlandpostcode.nl/v1/energy-label-radius?latitude=52.305285&longitude=4.750645&radius=150

Endpoints

Hieronder vind je een overzicht van de beschikbare endpoints van de Nederlandse Postcode API. Alle endpoints vereisen authenticatie met je API-key. Klik op een endpoint voor meer details en voorbeelden van requests en responses.

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 1012RJ en huisnummer 147 met coördinaten, wijk- en buurtnaam. Er is maar één adres voor deze combinatie.

GET https://api.nederlandpostcode.nl/v1/address?postcode=1012RJ&number=147&attributes[]=coordinates&attributes[]=district&attributes[]=neighborhood

{
    "data": [
        {
            "postcode": "1012RJ",
            "number": 147,
            "addition": null,
            "street": "Nieuwezijds Voorburgwal",
            "city": "Amsterdam",
            "municipality": "Amsterdam",
            "province": "Noord-Holland",
            "country": "Nederland",
            "details": {
                "district": {
                    "official": "Burgwallen-Nieuwe Zijde",
                    "name": "Burgwallen-Nieuwe Zijde"
                },
                "neighborhood": "Nieuwe Kerk e.o."
            },
            "coordinates": {
                "latitude": 52.37316211827917,
                "longitude": 4.890902032461384
            }
        }
    ]
}

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/address-range

Met het adresbereik-endpoint kun je alle adressen op dezelfde straat als een opgegeven adres ophalen. Het opgegeven postcode- en huisnummer worden gebruikt om de straat te bepalen.

Dit is bijvoorbeeld handig wanneer je alle woningen van een VvE, appartementencomplex of een bepaalde straat wilt ophalen. Omdat een straat meerdere postcodegebieden kan bevatten, kunnen de gevonden adressen verschillende postcodes hebben. Met start_number en end_number kun je het resultaat beperken tot een specifiek bereik van huisnummers. De resultaten worden gepagineerd met page en per_page. Met attributes[]=coordinates ontvang je per adres ook de coördinaten.

Query parameters

Voorbeeld

Onderstaande aanvraag gebruikt het opgegeven postcode- en huisnummer als referentie en haalt de eerste pagina op met maximaal 5 adressen op dezelfde straat.

GET https://api.nederlandpostcode.nl/v1/address-range?postcode=1118BN&number=800&per_page=5&page=1

{
    "data": [
        {
            "postcode": "1118BG",
            "number": 101,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "municipality": "Haarlemmermeer",
            "province": "Noord-Holland",
            "country": "Nederland"
        },
        {
            "postcode": "1118BG",
            "number": 103,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "municipality": "Haarlemmermeer",
            "province": "Noord-Holland",
            "country": "Nederland"
        },
        {
            "postcode": "1118BG",
            "number": 105,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "municipality": "Haarlemmermeer",
            "province": "Noord-Holland",
            "country": "Nederland"
        },
        {
            "postcode": "1118BG",
            "number": 107,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "municipality": "Haarlemmermeer",
            "province": "Noord-Holland",
            "country": "Nederland"
        },
        {
            "postcode": "1118BG",
            "number": 109,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "municipality": "Haarlemmermeer",
            "province": "Noord-Holland",
            "country": "Nederland"
        }
    ],
    "links": {
        "first": "https://api.nederlandpostcode.nl/v1/address-range?postcode=1118BN&number=800&page=1&per_page=5",
        "last": "https://api.nederlandpostcode.nl/v1/address-range?postcode=1118BN&number=800&page=41&per_page=5"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 41,
        "path": "https://api.nederlandpostcode.nl/v1/address-range",
        "per_page": 5,
        "to": 5,
        "total": 203
    }
}

Praktisch voorbeeld

Stel dat je de woningen van een VvE automatisch wilt aanmaken. De beheerder voert een adres in dat hij kent, bijvoorbeeld postcode 1118BN en huisnummer 800. De API gebruikt dit adres om de betreffende straat te bepalen. Vervolgens kun je met start_number en end_number bijvoorbeeld huisnummers 700 tot en met 900 opvragen. De API retourneert vervolgens alle adressen binnen dit bereik, inclusief de bijbehorende postcodes. Dit is vooral handig omdat een straat vaak meerdere postcodegebieden bevat: een reeks van bijvoorbeeld 10 tot 20 huisnummers kan dezelfde postcode hebben, waarna de volgende reeks een andere postcode krijgt.

Paginering

Een straat kan uit veel adressen bestaan. Daarom worden de resultaten automatisch over meerdere pagina's verdeeld. Gebruik page om een specifieke pagina op te vragen en per_page om het aantal resultaten per pagina in te stellen. De maximale waarde voor per_page is 50.

GET https://api.nederlandpostcode.nl/v1/address-range?postcode=1118BN&number=800&per_page=25&page=2

Filteren op huisnummer

Je kunt optioneel een bereik van huisnummers opgeven met start_number en end_number. Alleen adressen waarvan het huisnummer binnen dit bereik valt, worden teruggegeven. Wanneer start_number wordt opgegeven, is end_number ook verplicht, en andersom. Laat beide parameters weg om alle adressen op de betreffende straat op te vragen.

GET https://api.nederlandpostcode.nl/v1/address-range?postcode=1118BN&number=800&start_number=700&end_number=900

De meta-sectie van de response bevat informatie over de paginering, waaronder het huidige paginanummer, het aantal resultaten per pagina, het totale aantal pagina's en het totale aantal gevonden adressen. De links.first en links.last velden bevatten de URL's naar respectievelijk de eerste en laatste pagina.

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 /v2/energy-label

Met dit endpoint haal je alle energielabels van één specifiek adres op. Naast het gevalideerde adres (straat en woonplaats) krijg je de volledige energy_labels-array terug: niet alleen het actuele label, maar ook eventuele historische labels van hetzelfde pand, inclusief uitgebreide energieprestatiegegevens.

Wil je de energielabels van een hele straat of een reeks huisnummers in één keer opvragen? Gebruik dan het /v1/energy-label-range-endpoint. Zoek je de energielabels van alle adressen in de buurt van een locatie, gebruik dan het /v1/energy-label-radius-endpoint.

Query parameters

Voorbeeld met enkel adres

Dit voorbeeld haalt de energielabels op voor postcode 1118BN en huisnummer 800.

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

{
    "data": {
        "postcode": "1118BN",
        "number": 800,
        "addition": null,
        "street": "Schiphol Boulevard",
        "city": "Schiphol",
        "energy_labels": [
            {
                "registration_date": "30-08-2022",
                "inspection_date": "02-08-2022",
                "valid_until_date": "02-08-2032",
                "status": "bestaand",
                "construction_type": "utiliteitsbouw",
                "building_type": null,
                "energy_label": "A+++",
                "calculation_type": "NTA 8800:2022 (basisopname utiliteitsbouw)",
                "inspection_type": "basis",
                "construction_year": 2019,
                "thermal_zone_area": 5648.39,
                "compactness": 1.16,
                "energy_demand": 98.4,
                "energy_demand_requirement": null,
                "primary_fossil_energy": 55.48,
                "primary_fossil_energy_requirement": null,
                "primary_fossil_energy_emg": null,
                "renewable_energy_share": 55.3,
                "renewable_energy_share_requirement": null,
                "renewable_energy_share_emg": null,
                "calculated_energy_consumption": 55.48,
                "heat_demand": 55.02,
                "calculated_co2_emission": 13.01,
                "temperature_excess": 0,
                "temperature_excess_requirement": null
            }
        ]
    }
}

Voorbeeld met een adres zonder energielabel

Bestaat het adres wel, maar is er geen energielabel voor geregistreerd? Dan is dat geen fout: je krijgt een 200 OK met de adresvelden gevuld en een lege energy_labels-array. Controleer dus op een lege array in plaats van op een foutcode.

{
    "data": {
        "postcode": "...",
        "number": ...,
        "addition": null,
        "street": "...",
        "city": "...",
        "energy_labels": []
    }
}

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. Bij meerdere adressen kies je het juiste adres door ook addition mee te sturen. Wil je het adres zonder toevoeging, stuur dan een lege addition= mee.

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

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

Een uitgebreide uitleg van alle velden in de response, zoals de BENG-indicatoren en de mogelijke labelklassen, vind je in de Energielabel API-documentatie op EnergielabelAPI.nl.

GET /v1/energy-label-range

Met het energielabel-range-endpoint vraag je de energielabels van meerdere adressen in één request op: van een hele straat of van een specifieke reeks huisnummers binnen die straat. Dit is bijvoorbeeld handig voor een appartementencomplex, een VvE of een bouwblok.

Net als bij het adresbereik-endpoint worden de opgegeven postcode en het huisnummer gebruikt om de straat te bepalen. Omdat een straat meerdere postcodegebieden kan bevatten, kunnen de gevonden adressen verschillende postcodes hebben.

Dit endpoint werkt op een aantal punten anders dan /v2/energy-label:

• Per adres krijg je alleen het meest recente energielabel terug, als object energy_label (enkelvoud), zonder historie. Wil je de volledige labelhistorie van een adres, gebruik dan /v2/energy-label.
• Alleen adressen waarvoor minimaal één energielabel is geregistreerd worden teruggegeven. Een huisnummer zonder label komt niet in de response voor.
• De resultaten worden gepagineerd met page en per_page.

Query parameters

Voorbeeld

Onderstaande aanvraag gebruikt postcode 1118BN en huisnummer 800 als referentie en haalt de energielabels op van de huisnummers 700 tot en met 900 in dezelfde straat. Alleen de adressen met een geregistreerd energielabel worden teruggegeven.

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

{
    "data": [
        {
            "postcode": "1118BN",
            "number": 701,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "energy_label": {
                "registration_date": "30-04-2026",
                "inspection_date": "23-03-2026",
                "valid_until_date": "23-03-2036",
                "status": "bestaand",
                "construction_type": "utiliteitsbouw",
                "building_type": null,
                "energy_label": "A+",
                "calculation_type": "NTA 8800:2024 (detailopname utiliteitsbouw)",
                "inspection_type": "detail",
                "construction_year": 2015,
                "thermal_zone_area": 25941.84,
                "compactness": 0.51,
                "energy_demand": 54.33,
                "energy_demand_requirement": null,
                "primary_fossil_energy": 162.4,
                "primary_fossil_energy_requirement": null,
                "primary_fossil_energy_emg": null,
                "renewable_energy_share": 23.5,
                "renewable_energy_share_requirement": null,
                "renewable_energy_share_emg": null,
                "calculated_energy_consumption": 162.39,
                "heat_demand": 7.31,
                "calculated_co2_emission": 34.25,
                "temperature_excess": null,
                "temperature_excess_requirement": null
            }
        },
        {
            "postcode": "1118BN",
            "number": 800,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "energy_label": {
                "registration_date": "30-08-2022",
                "inspection_date": "02-08-2022",
                "valid_until_date": "02-08-2032",
                "status": "bestaand",
                "construction_type": "utiliteitsbouw",
                "building_type": null,
                "energy_label": "A+++",
                "calculation_type": "NTA 8800:2022 (basisopname utiliteitsbouw)",
                "inspection_type": "basis",
                "construction_year": 2019,
                "thermal_zone_area": 5648.39,
                "compactness": 1.16,
                "energy_demand": 98.4,
                "energy_demand_requirement": null,
                "primary_fossil_energy": 55.48,
                "primary_fossil_energy_requirement": null,
                "primary_fossil_energy_emg": null,
                "renewable_energy_share": 55.3,
                "renewable_energy_share_requirement": null,
                "renewable_energy_share_emg": null,
                "calculated_energy_consumption": 55.48,
                "heat_demand": 55.02,
                "calculated_co2_emission": 13.01,
                "temperature_excess": 0,
                "temperature_excess_requirement": null
            }
        }
    ],
    "links": {
        "first": "https://api.nederlandpostcode.nl/v1/energy-label-range?postcode=1118BN&number=800&start_number=700&end_number=900&page=1",
        "last": "https://api.nederlandpostcode.nl/v1/energy-label-range?postcode=1118BN&number=800&start_number=700&end_number=900&page=1"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.nederlandpostcode.nl/v1/energy-label-range",
        "per_page": 10,
        "to": 2,
        "total": 2
    }
}

Het energy_label-object bevat dezelfde velden als de items in de energy_labels-array van /v2/energy-label.

Paginering

Gebruik page om een specifieke pagina op te vragen en per_page om het aantal resultaten per pagina in te stellen (maximaal 25). De meta- en links-secties zijn gelijk aan die van het adresbereik-endpoint; meta.total telt alleen de adressen met een energielabel. Laat start_number en end_number weg om de energielabels van de hele straat op te vragen.

Geen adres of geen energielabels gevonden

Kan het opgegeven referentieadres niet gevonden worden, dan krijg je een 422 Unprocessable Content met de melding No address found for the given postcode and number. Zijn er binnen het opgegeven bereik geen adressen met een energielabel, dan krijg je een 200 OK met een lege data-array.

Een uitgebreide uitleg van alle velden in de response, zoals de BENG-indicatoren en de mogelijke labelklassen, vind je in de Energielabel API-documentatie op EnergielabelAPI.nl.

GET /v1/energy-label-radius

Met het energielabel-radius-endpoint vraag je in één request de energielabels op van alle adressen binnen een straal rond een coördinaat. Dit is bijvoorbeeld handig om de energielabels in de buurt op een kaart te tonen, een woning met de omgeving te vergelijken of een wijk te analyseren.

De resultaten zijn gesorteerd op afstand tot het opgegeven punt, het dichtstbijzijnde adres eerst. Adressen op dezelfde afstand, zoals appartementen in hetzelfde gebouw, worden gesorteerd op postcode, huisnummer en toevoeging. Heb je alleen een adres? Haal dan eerst de coördinaten op via het adres-endpoint met attributes[]=coordinates.

Dit endpoint werkt op een aantal punten anders dan de andere energielabel-endpoints:

• Per adres krijg je alleen de labelklasse van het meest recente energielabel terug, als tekst in het veld energy_label (bijv. "A+"), zonder de overige energieprestatiegegevens. Wil je alle gegevens of de labelhistorie van een adres, gebruik dan /v2/energy-label.
• Alleen adressen waarvoor minimaal één energielabel is geregistreerd worden teruggegeven. Een huisnummer zonder label komt niet in de response voor.
• Ieder adres bevat altijd de coordinates en de distance tot het opgegeven punt. De parameter attributes[] wordt bij dit endpoint niet ondersteund.
• De resultaten worden gepagineerd met page en per_page.

Query parameters

Voorbeeld

Onderstaande aanvraag haalt de energielabels op van alle adressen binnen 150 meter van Schiphol Boulevard 800 (latitude: 52.305285, longitude: 4.750645). Alleen de adressen met een geregistreerd energielabel worden teruggegeven.

GET https://api.nederlandpostcode.nl/v1/energy-label-radius?latitude=52.305285&longitude=4.750645&radius=150

{
    "data": [
        {
            "postcode": "1118BN",
            "number": 800,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "coordinates": {
                "latitude": 52.30528553688755,
                "longitude": 4.750645160863609
            },
            "distance": 0,
            "energy_label": "A+++"
        },
        {
            "postcode": "1118CX",
            "number": 308,
            "addition": null,
            "street": "Evert van de Beekstraat",
            "city": "Schiphol",
            "coordinates": {
                "latitude": 52.30482565215747,
                "longitude": 4.749222421097077
            },
            "distance": 110,
            "energy_label": "A+"
        },
        {
            "postcode": "1118CL",
            "number": 1,
            "addition": null,
            "street": "Evert van de Beekstraat",
            "city": "Schiphol",
            "coordinates": {
                "latitude": 52.30549394509628,
                "longitude": 4.752529225036044
            },
            "distance": 130,
            "energy_label": "A+"
        }
    ],
    "links": {
        "first": "https://api.nederlandpostcode.nl/v1/energy-label-radius?latitude=52.305285&longitude=4.750645&radius=150&page=1",
        "last": "https://api.nederlandpostcode.nl/v1/energy-label-radius?latitude=52.305285&longitude=4.750645&radius=150&page=1"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.nederlandpostcode.nl/v1/energy-label-radius",
        "per_page": 10,
        "to": 3,
        "total": 3
    }
}

Het veld distance is de afstand in hele meters tussen het opgegeven punt en het adres. Het veld energy_label bevat de labelklasse van het meest recente energielabel (A+++++ t/m G), of null als er voor dat label geen labelklasse bekend is.

Paginering

Gebruik page om een specifieke pagina op te vragen en per_page om het aantal resultaten per pagina in te stellen (maximaal 25). De meta- en links-secties zijn gelijk aan die van het adresbereik-endpoint; meta.total telt alleen de adressen met een energielabel binnen de straal.

Geen energielabels gevonden of ongeldige parameters

Zijn er binnen de straal geen adressen met een energielabel, dan krijg je een 200 OK met een lege data-array. Ontbreekt een verplichte parameter of is een waarde ongeldig, bijvoorbeeld een straal groter dan 1000 meter, dan krijg je een 422 Unprocessable Content met een validatiefout.

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 zijn 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-key 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 API-key om overbelasting van de server te voorkomen en je API-key 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 seconde

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

{
    "message": "Rate limit exceeded.",
    "quota": {
        "strategy": "per_second",
        "limit": 10
    }
}

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

In deze lijst vind je plugins die door ons en onze partners zijn ontwikkeld. Deze plugins maken het makkelijker om adresvalidatie te integreren in jouw webshop of website.

De plugins voor WordPress en andere e-commerceplatforms worden door Postcode Checkout onderhouden; zij bieden ook ondersteuning en hulp bij installatie van deze plugins.

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