NAV
bash javascript

Postcodes.nu API

Met behulp van deze documentatie kan de API geïmplementeerd worden in uw applicatie. Daarnaast hebben wij ook een PHP library geschreven de implementatie van onze API nog makklijker te maken, wel zo handig.

Authenticatie

De postcodes.nu API maakt gebruik van authenticatie met behulp van een token. Voordat er gebruik gemaakt kan worden van de API, moet dus dit token opgehaald worden.

Login

Login en genereer token.

Voorbeeld request:

curl -X POST "https://postcodes.nu/api/auth/login" \
    -H "Accept: application/json" \
    -H "X-Requested-With: XMLHttpRequest" \
    -H "Content-Type: application/json" \
    -d '{"email":"test@kees.com","password":"P@$$w0rd"}'

const url = new URL("https://postcodes.nu/api/auth/login");

let headers = {
    "Accept": "application/json",
    "X-Requested-With": "XMLHttpRequest",
    "Content-Type": "application/json",
}

let body = {
    "email": "test@kees.com",
    "password": "P@$$w0rd"
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));

Voorbeeld response (200):

{
    "access_token": "{token}",
    "token_type": "Bearer",
    "expires_at": "{date}"
}

HTTP Request

POST api/auth/login

Body Parameters

Parameter Type Status Description
email email required Email adres.
password string required Wachtwoord.

Versie 1

API's voor het ophalen van gegevens

Basic postcode check

Deze functie kijkt of een postcode bestaat. Daarnaast kijkt deze functie ook of de postcode een geldig formaat heeft.

Voorbeeld request:

curl -X GET -G "https://postcodes.nu/api/v1/postcode/exists/{postcode}" \
    -H "Accept: application/json" \
    -H "X-Requested-With: XMLHttpRequest" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {token}" \
    -H "abonnement-id: {abonnement-id}"
const url = new URL("https://postcodes.nu/api/v1/postcode/exists/{postcode}");

    let params = {
            "token": "M6H7wXAwgEFywTqc",
            "abonnement-id": "DfaCBLB6lngyx5Ma",
            "postcode": "4rJa8xevD1jov3J7",
        };
    Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Accept": "application/json",
    "X-Requested-With": "XMLHttpRequest",
    "Content-Type": "application/json",
    "Authorization": "Bearer {token}",
    "abonnement-id": "{abonnement-id}",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

Voorbeeld response (200):

{
    "exists": true,
    "valid_format": true
}

HTTP Request

GET api/v1/postcode/exists/{postcode}

Query Parameters

Parameter Status Description
token required Bearer token.
abonnement-id required Abonnement ID.
postcode required De postcode.

Letters bij postcode

Deze functie geeft alle letters terug die horen bij de getallen van een postcode.

Voorbeeld request:

curl -X GET -G "https://postcodes.nu/api/v1/postcode/{postcode}/letters" \
    -H "Accept: application/json" \
    -H "X-Requested-With: XMLHttpRequest" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {token}" \
    -H "abonnement-id: {abonnement-id}"
const url = new URL("https://postcodes.nu/api/v1/postcode/{postcode}/letters");

    let params = {
            "token": "jKAc4Qf7wrU7docw",
            "abonnement-id": "cic7Zi88wm80qMOs",
            "postcode": "nVY1tWpCtAy2bf4s",
        };
    Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Accept": "application/json",
    "X-Requested-With": "XMLHttpRequest",
    "Content-Type": "application/json",
    "Authorization": "Bearer {token}",
    "abonnement-id": "{abonnement-id}",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

Voorbeeld response (200):

{
    "results": [
        "9999AA",
        "9999XB",
        "9999XE",
        "9999XG",
        "9999XH",
        "9999XJ",
        "9999XK",
        "9999XL",
        "9999XX",
        "9999ZZ"
    ],
    "valid_format": true
}

HTTP Request

GET api/v1/postcode/{postcode}/letters

Query Parameters

Parameter Status Description
token required Bearer token.
abonnement-id required Abonnement ID.
postcode required De getallen van de postcode.

Huisnummers bij postcode

Deze functie geeft alle huisnummers terug die horen bij de opgegeven postcode. Daarnaast worden ook de huisnummer toevoegingen mee terug gestuurd.

Voorbeeld request:

curl -X GET -G "https://postcodes.nu/api/v1/postcode/{postcode}/huisnummers" \
    -H "Accept: application/json" \
    -H "X-Requested-With: XMLHttpRequest" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {token}" \
    -H "abonnement-id: {abonnement-id}"
const url = new URL("https://postcodes.nu/api/v1/postcode/{postcode}/huisnummers");

    let params = {
            "token": "VfgkTq8Cgf90PyL9",
            "abonnement-id": "8Ntt5H9HXw7b5NCJ",
            "postcode": "k4F6VhQy3S7md3Lu",
        };
    Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Accept": "application/json",
    "X-Requested-With": "XMLHttpRequest",
    "Content-Type": "application/json",
    "Authorization": "Bearer {token}",
    "abonnement-id": "{abonnement-id}",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

Voorbeeld response (200):

{
    "results": [
        {
            "identificatie": "0847200000376896",
            "huisnummer": "998",
            "huisnummer_toevoeging": "1",
            "huisletter": "T"
        },
        {
            "identificatie": "0847200000376897",
            "huisnummer": "998",
            "huisnummer_toevoeging": "2l",
            "huisletter": "T"
        },
        {
            "identificatie": "0847200000376898",
            "huisnummer": "998",
            "huisnummer_toevoeging": "3",
            "huisletter": "T"
        },
        {
            "identificatie": "0847200000376899",
            "huisnummer": "998",
            "huisnummer_toevoeging": "4",
            "huisletter": "T"
        }
    ]
}

HTTP Request

GET api/v1/postcode/{postcode}/huisnummers

Query Parameters

Parameter Status Description
token required Bearer token.
abonnement-id required Abonnement ID.
postcode required De postcode.

Huis selecteren

Deze functie geeft alle informatie terug die hoort bij de opgegeven postcode + huisnummer combinatie. Bij het gebruik van deze API call zijn er vier opties mogelijk: alleen een huisnummer, een huisnummer met huisnummer toevoeging, een huisnummer met huisnummer toevoeging en huisletter, een huisnummer met huisletter.

Voorbeeld request:

curl -X GET -G "https://postcodes.nu/api/v1/postcode/{postcode}/{huisnummer}/{huisnummer_toevoeging}/{huisletter}" \
    -H "Accept: application/json" \
    -H "X-Requested-With: XMLHttpRequest" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {token}" \
    -H "abonnement-id: {abonnement-id}"
const url = new URL("https://postcodes.nu/api/v1/postcode/{postcode}/{huisnummer}/{huisnummer_toevoeging}/{huisletter}");

    let params = {
            "token": "{BMEVcpiaF5sunjjq}",
            "abonnement-id": "JOXcyoNvQSUw89xF",
            "postcode": "vyEx4czHhpHhoOuL",
            "huisnummer": "9ruNeegM3tLKXiSg",
            "huisnummer_toevoeging": "QAT8C0pHizeKRbRB",
            "huisletter": "TWWb7v5tzuJBSMud",
        };
    Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Accept": "application/json",
    "X-Requested-With": "XMLHttpRequest",
    "Content-Type": "application/json",
    "Authorization": "Bearer {token}",
    "abonnement-id": "{abonnement-id}",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

Voorbeeld response (200):

{
    "result": {
        "identificatie": "0847200000376896",
        "postcode": "9999AA",
        "huisnummer": "998",
        "huisnummer_toevoeging": "1",
        "huisletter": "T",
        "straat": "Bosrandweg",
        "straat_nen5825": "",
        "plaats": "Someren",
        "provincie": "Groningen",
        "gebruiksdoelVerblijfsobject": "overige gebruiksfunctie",
        "oppervlakteVerblijfsobject": "20"
    },
    "hasResult": true
}

HTTP Request

GET api/v1/postcode/{postcode}/{huisnummer}

GET api/v1/postcode/{postcode}/{huisnummer}/{huisnummer_toevoeging}

GET api/v1/postcode/{postcode}/{huisnummer}/{huisnummer_toevoeging}/{huisletter}

GET api/v1/postcode/{postcode}/{huisnummer}//{huisletter}

Query Parameters

Parameter Status Description
token required Bearer token.
abonnement-id required Abonnement ID.
postcode required De postcode.
huisnummer required Het huisnummer.
huisnummer_toevoeging optional De huisnummertoevoeging.
huisletter optional De huisletter.

Libraries

Errors

De Postcode.nu API maakt gebruik van de volgende error codes:

Status Errors

Error Code Betekenis
401 Unauthorized -- De meegestuurde token is ongeldig.
422 Unprocessable Entity -- De request is goed, maar inhoudelijk zijn er fouten (meegestuurde variabelen).

Response Errors

Error Code Betekenis
"valid_format": false Het formaat van meegestuurde query parameters is incorrect.
"hasResult": false De uitgevoerde call heeft geen resultaten opgeleverd.
bash javascript