NAV -image
bash php python javascript

Introduction

Welcome to the official Postcode Service API documentation!

The most up to date postcode service for the Netherlands and Belgium. Our clients have saved yearly over 1 million euro in RMA (Return Material Authorization).

Questions?

You can contact our experts via support@postcodeservice.com or call our office in Amsterdam +31 20 218 1024.

Plugins & extensions

There is a ready-to-use Magento 2 extension on github: tig-nl/postcode-magento2. For installation support you can contact our experts support@postcodeservice.com or call our office in Amsterdam +31 20 218 1024.

Authenticating requests

Authenticate requests to this API's endpoints by sending a X-Secure_Code header with the value "{your-token}".

And header X-Client_Id with {YOUR_CLIENT_ID}. You can retrieve your credentials by visiting our https://postcodeservice.com.

Try it yourself, right now!

You can use these test credentials. Keep in mind there is a daily maximum.

X-Client_Id1177
X-Secure_Code9SRLYBCALURPE2B
X-Domain (optional)https://postcodeservice.com/

Rate limited

If a response code 429 (429 Too Many Requests is visible in the browser) is returned, you have reached the maximum number of requests per second specified in your contract. The default is 10 requests/seconds. As soon as the number of requests falls below the maximum number again (standard <10 requests/s) you will receive the usual responses again. You can contact your account manager on telephone number +31 20 218 1024 if you want to increase the number of requests.

Belgium API v2

Version 2 of the Belgium zip code validation will be maintained throughout 2022.

find - Completes a street name

requires authentication

This endpoint expects a part of a street name and will return a list of all street names which start with the given string.

Example request:

curl -X GET \
    -G "https://api.postcodeservice.com/be/v2/find?street=Koningin+Maria" \
    -H "X-Secure_Code: 9SRLYBCALURPE2B" \
    -H "X-Client_Id: 1177" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.postcodeservice.com/be/v2/find',
    [
        'headers' => [
            'X-Secure_Code' => '9SRLYBCALURPE2B',
            'X-Client_Id' => '1177',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'street'=> 'Koningin Maria',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.postcodeservice.com/be/v2/find'
params = {
  'street': 'Koningin Maria',
}
headers = {
  'X-Secure_Code': '9SRLYBCALURPE2B',
  'X-Client_Id': '1177',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
    "https://api.postcodeservice.com/be/v2/find"
);

let params = {
    "street": "Koningin Maria",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-Secure_Code": "9SRLYBCALURPE2B",
    "X-Client_Id": "1177",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

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

Example response (200):

{
    "0": {
        "label": "Koningin Maria Hendrikaplein - Gent",
        "type": "Street",
        "postcode": 9000,
        "city": "Gent",
        "street": "Koningin Maria Hendrikaplein"
    },
    "1": {
        "label": "Koningin Maria-Henriettelaan - Leopoldsburg",
        "type": "Street",
        "postcode": 3970,
        "city": "Leopoldsburg",
        "street": "Koningin Maria-Henriettelaan"
    }
}

Request

GET be/v2/find

Query Parameters

street  string
Part of a street name to complete, example: Koningin Maria.

postcode-find - Completes a zip code or city name

requires authentication

This endpoint expects a part of zipcode or city name and will return a list of matches.

Example request:

curl -X GET \
    -G "https://api.postcodeservice.com/be/v2/postcode-find?zipcodezone=1040" \
    -H "X-Secure_Code: 9SRLYBCALURPE2B" \
    -H "X-Client_Id: 1177" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.postcodeservice.com/be/v2/postcode-find',
    [
        'headers' => [
            'X-Secure_Code' => '9SRLYBCALURPE2B',
            'X-Client_Id' => '1177',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'zipcodezone'=> '1040',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.postcodeservice.com/be/v2/postcode-find'
params = {
  'zipcodezone': '1040',
}
headers = {
  'X-Secure_Code': '9SRLYBCALURPE2B',
  'X-Client_Id': '1177',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
    "https://api.postcodeservice.com/be/v2/postcode-find"
);

let params = {
    "zipcodezone": "1040",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-Secure_Code": "9SRLYBCALURPE2B",
    "X-Client_Id": "1177",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

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

Example response (200):

[
    {
        "postcode": 1040,
        "plaats": "Brussel"
    },
    {
        "postcode": 1040,
        "plaats": "Etterbeek"
    }
]

Request

GET be/v2/postcode-find

Query Parameters

zipcodezone  string
Part of a zip code or city name to complete, example: 1040 or Brussel.

street-find - Completes the street name based on zip code and city name

requires authentication

This endpoint needs a correct zip code, city name and part of a street name. It will return all found matches.

Example request:

curl -X GET \
    -G "https://api.postcodeservice.com/be/v2/street-find?zipcode=1040&city=Brussel&street=Rue+de+la" \
    -H "X-Secure_Code: 9SRLYBCALURPE2B" \
    -H "X-Client_Id: 1177" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.postcodeservice.com/be/v2/street-find',
    [
        'headers' => [
            'X-Secure_Code' => '9SRLYBCALURPE2B',
            'X-Client_Id' => '1177',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'zipcode'=> '1040',
            'city'=> 'Brussel',
            'street'=> 'Rue de la',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.postcodeservice.com/be/v2/street-find'
params = {
  'zipcode': '1040',
  'city': 'Brussel',
  'street': 'Rue de la',
}
headers = {
  'X-Secure_Code': '9SRLYBCALURPE2B',
  'X-Client_Id': '1177',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
    "https://api.postcodeservice.com/be/v2/street-find"
);

let params = {
    "zipcode": "1040",
    "city": "Brussel",
    "street": "Rue de la",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-Secure_Code": "9SRLYBCALURPE2B",
    "X-Client_Id": "1177",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

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

Example response (200):


[
  {
    "straat": "Rue de la Loi",
  },
  {
    "straat": "Rue de la Science",
  },
  {
    "straat": "Rue de la Verveine",
  }
]

Request

GET be/v2/street-find

Query Parameters

zipcode  string
a zip code, example: 1040.

city  string
a city name, example: Brussel.

street  string
a partial street name, example: Rue de la.

Belgium API v3

Version 3 of the Belgium zip code validation has more features over Version 2.

find - Completes a street name

requires authentication

This endpoint expects a part of a street name and will return a list of all street names which start with the given string.

Example request:

curl -X GET \
    -G "https://api.postcodeservice.com/be/v3/find?street=Koningin+Maria" \
    -H "X-Secure_Code: 9SRLYBCALURPE2B" \
    -H "X-Client_Id: 1177" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.postcodeservice.com/be/v3/find',
    [
        'headers' => [
            'X-Secure_Code' => '9SRLYBCALURPE2B',
            'X-Client_Id' => '1177',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'street'=> 'Koningin Maria',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.postcodeservice.com/be/v3/find'
params = {
  'street': 'Koningin Maria',
}
headers = {
  'X-Secure_Code': '9SRLYBCALURPE2B',
  'X-Client_Id': '1177',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
    "https://api.postcodeservice.com/be/v3/find"
);

let params = {
    "street": "Koningin Maria",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-Secure_Code": "9SRLYBCALURPE2B",
    "X-Client_Id": "1177",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

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

Example response (200):

{
    "0": {
        "city": "Gent",
        "label": "Koningin Maria Hendrikaplein - Gent (9000)",
        "street": "Koningin Maria Hendrikaplein",
        "streetid": 900032325761763596,
        "streetlang": "nl",
        "type": "Street",
        "zipcode": 9000
    },
    "1": {
        "city": "Vorst",
        "label": "Koningin Maria-Hendrikalaan - Vorst (1190)",
        "street": "Koningin Maria-Hendrikalaan",
        "streetid": 119056521757555936,
        "streetlang": "nl",
        "type": "Street",
        "zipcode": 1190
    },
    "2": {
        "city": "Leopoldsburg",
        "label": "Koningin Maria-Henriettelaan - Leopoldsburg (3970)",
        "street": "Koningin Maria-Henriettelaan",
        "streetid": 397025451615544216,
        "streetlang": "nl",
        "type": "Street",
        "zipcode": 3970
    }
}

Request

GET be/v3/find

Query Parameters

street  string
Part of a street name to complete, example: Koningin Maria.

postcode-find - Completes a zip code or city name (same as zipcode-find)

requires authentication

This endpoint expects a part of zipcode or city name and will return a list of matches. There are optional settings to get city names in specific or multiple language facilities.

Example request:

curl -X GET \
    -G "https://api.postcodeservice.com/be/v3/postcode-find?zipcodezone=1050&language=fr&multiresults=0" \
    -H "X-Secure_Code: 9SRLYBCALURPE2B" \
    -H "X-Client_Id: 1177" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.postcodeservice.com/be/v3/postcode-find',
    [
        'headers' => [
            'X-Secure_Code' => '9SRLYBCALURPE2B',
            'X-Client_Id' => '1177',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'zipcodezone'=> '1050',
            'language'=> 'fr',
            'multiresults'=> '0',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.postcodeservice.com/be/v3/postcode-find'
params = {
  'zipcodezone': '1050',
  'language': 'fr',
  'multiresults': '0',
}
headers = {
  'X-Secure_Code': '9SRLYBCALURPE2B',
  'X-Client_Id': '1177',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
    "https://api.postcodeservice.com/be/v3/postcode-find"
);

let params = {
    "zipcodezone": "1050",
    "language": "fr",
    "multiresults": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-Secure_Code": "9SRLYBCALURPE2B",
    "X-Client_Id": "1177",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

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

Example response (200):

[
    {
        "zipcode": 1050,
        "city": "Bruxelles"
    },
    {
        "zipcode": 1050,
        "city": "Ixelles"
    },
    {
        "zipcode": 1050,
        "city": "Saint-Gilles"
    }
]

Example response (200, multiresults=1):

[
    {
        "city": "Brussel",
        "zipcode": 1050
    },
    {
        "city": "Elsene",
        "zipcode": 1050
    },
    {
        "city": "Sint-Gillis",
        "zipcode": 1050
    },
    {
        "city": "Bruxelles",
        "zipcode": 1050
    },
    {
        "city": "Ixelles",
        "zipcode": 1050
    },
    {
        "city": "Saint-Gillis",
        "zipcode": 1050
    }
]

Request

GET be/v3/postcode-find

Query Parameters

zipcodezone  string
Part of a zip code or city name to complete, example: 1050 or Brussel.

language  string optional
Can contain the preferred language you want the results in for municipalities with language facilities, example: fr.

multiresults  string optional
Allow multiple results for municipalities with language facilities, works for zip codes, by default off, example: 0.

zipcode-find - Completes a zipcode or city name

requires authentication

Same as postcode-find. This endpoint expects a part of zipcode or city name and will return a list of matches. There are optional settings to get city names in specific or multiple language facilities.

Example request:

curl -X GET \
    -G "https://api.postcodeservice.com/be/v3/zipcode-find?zipcodezone=1050&language=fr&multiresults=0" \
    -H "X-Secure_Code: 9SRLYBCALURPE2B" \
    -H "X-Client_Id: 1177" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.postcodeservice.com/be/v3/zipcode-find',
    [
        'headers' => [
            'X-Secure_Code' => '9SRLYBCALURPE2B',
            'X-Client_Id' => '1177',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'zipcodezone'=> '1050',
            'language'=> 'fr',
            'multiresults'=> '0',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.postcodeservice.com/be/v3/zipcode-find'
params = {
  'zipcodezone': '1050',
  'language': 'fr',
  'multiresults': '0',
}
headers = {
  'X-Secure_Code': '9SRLYBCALURPE2B',
  'X-Client_Id': '1177',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
    "https://api.postcodeservice.com/be/v3/zipcode-find"
);

let params = {
    "zipcodezone": "1050",
    "language": "fr",
    "multiresults": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-Secure_Code": "9SRLYBCALURPE2B",
    "X-Client_Id": "1177",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

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

Example response (200):

[
    {
        "zipcode": 1050,
        "city": "Bruxelles"
    },
    {
        "zipcode": 1050,
        "city": "Ixelles"
    }
]

Example response (200, multiresults=1):

[
    {
        "city": "Brussel",
        "zipcode": 1050
    },
    {
        "city": "Elsene",
        "zipcode": 1050
    },
    {
        "city": "Bruxelles",
        "zipcode": 1050
    },
    {
        "city": "Ixelles",
        "zipcode": 1050
    }
]

Request

GET be/v3/zipcode-find

Query Parameters

zipcodezone  string
Part of a zipcode or city name to complete, example: 1050 or Brussel.

language  string optional
Can contain the preferred language you want the results in for municipalities with language facilities, example: fr.

multiresults  string optional
Allow multiple results for municipalities with language facilities, works for zip codes, by default off, example: 0.

street-find - Completes the street name based on zip code and city name

requires authentication

This endpoint expects a correct zipcode and city name and a part of a street name. It will return matches street names.

Example request:

curl -X GET \
    -G "https://api.postcodeservice.com/be/v3/street-find?zipcode=1040&city=Brussel&street=Rue+de+C" \
    -H "X-Secure_Code: 9SRLYBCALURPE2B" \
    -H "X-Client_Id: 1177" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.postcodeservice.com/be/v3/street-find',
    [
        'headers' => [
            'X-Secure_Code' => '9SRLYBCALURPE2B',
            'X-Client_Id' => '1177',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'zipcode'=> '1040',
            'city'=> 'Brussel',
            'street'=> 'Rue de C',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.postcodeservice.com/be/v3/street-find'
params = {
  'zipcode': '1040',
  'city': 'Brussel',
  'street': 'Rue de C',
}
headers = {
  'X-Secure_Code': '9SRLYBCALURPE2B',
  'X-Client_Id': '1177',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
    "https://api.postcodeservice.com/be/v3/street-find"
);

let params = {
    "zipcode": "1040",
    "city": "Brussel",
    "street": "Rue de C",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-Secure_Code": "9SRLYBCALURPE2B",
    "X-Client_Id": "1177",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

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

Example response (200):

[
    {
        "street": "Rue de Chambéry",
        "streetid": 104077915151295985,
        "streetlang": "fr"
    },
    {
        "street": "Rue de Comines",
        "streetid": 104037492375926662,
        "streetlang": "fr"
    }
]

Request

GET be/v3/street-find

Query Parameters

zipcode  string
a zip code, example: 1040.

city  string
a city name, example: Brussel.

street  string
a partial street name, example: Rue de C.

houseno-find - Find house numbers and addons for a given street name

requires authentication

This endpoint expects a zip code, city name and street name and will return all house numbers and addons for the street.

Alternatively you can use the streetid: This endpoint expects a streetid and will return all the house numbers and addons for the street.

Example request:

curl -X GET \
    -G "https://api.postcodeservice.com/be/v3/houseno-find?zipcode=9000&city=Gent&street=Vliegtuiglaan&streetid=900093267659932423" \
    -H "X-Secure_Code: 9SRLYBCALURPE2B" \
    -H "X-Client_Id: 1177" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.postcodeservice.com/be/v3/houseno-find',
    [
        'headers' => [
            'X-Secure_Code' => '9SRLYBCALURPE2B',
            'X-Client_Id' => '1177',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'zipcode'=> '9000',
            'city'=> 'Gent',
            'street'=> 'Vliegtuiglaan',
            'streetid'=> '900093267659932423',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.postcodeservice.com/be/v3/houseno-find'
params = {
  'zipcode': '9000',
  'city': 'Gent',
  'street': 'Vliegtuiglaan',
  'streetid': '900093267659932423',
}
headers = {
  'X-Secure_Code': '9SRLYBCALURPE2B',
  'X-Client_Id': '1177',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
    "https://api.postcodeservice.com/be/v3/houseno-find"
);

let params = {
    "zipcode": "9000",
    "city": "Gent",
    "street": "Vliegtuiglaan",
    "streetid": "900093267659932423",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-Secure_Code": "9SRLYBCALURPE2B",
    "X-Client_Id": "1177",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

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

Example response (200):


{
     "1": {
         "zipcode": 9000,
         "city": "Gent",
         "street": "Vliegtuiglaan",
         "houseno": "5",
         "addon": "",
         "box": "",
         "streetlang": "nl"
     },
     "2": {
         "zipcode": 9000,
         "city": "Gent",
         "street": "Vliegtuiglaan",
         "houseno": "6",
         "addon": "",
         "box": "",
         "streetlang": "nl"
     },
     ...
 }

Request

GET be/v3/houseno-find

Query Parameters

zipcode  string
a zip code, example: 9000.

city  string
a city name, example: Gent.

street  string
a street name, example: Vliegtuiglaan.

streetid  string optional
Can be retrieved with 'street-find' call, example: 900093267659932423.

houseno-match - Exactly match a house number

requires authentication

This endpoint expects a zip code, city name and street name, house number and will return if the house number exists.

Alternatively you can use the streetid: This endpoint expects a streetid and house number and will return if the housenumber exists.

Example request:

curl -X GET \
    -G "https://api.postcodeservice.com/be/v3/houseno-match?zipcode=9700&city=Oudenaarde&street=Aalststraat&streetid=970098157329689625&houseno=2&addon=A&strict=0&only_status=0" \
    -H "X-Secure_Code: 9SRLYBCALURPE2B" \
    -H "X-Client_Id: 1177" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.postcodeservice.com/be/v3/houseno-match',
    [
        'headers' => [
            'X-Secure_Code' => '9SRLYBCALURPE2B',
            'X-Client_Id' => '1177',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'zipcode'=> '9700',
            'city'=> 'Oudenaarde',
            'street'=> 'Aalststraat',
            'streetid'=> '970098157329689625',
            'houseno'=> '2',
            'addon'=> 'A',
            'strict'=> '0',
            'only_status'=> '0',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.postcodeservice.com/be/v3/houseno-match'
params = {
  'zipcode': '9700',
  'city': 'Oudenaarde',
  'street': 'Aalststraat',
  'streetid': '970098157329689625',
  'houseno': '2',
  'addon': 'A',
  'strict': '0',
  'only_status': '0',
}
headers = {
  'X-Secure_Code': '9SRLYBCALURPE2B',
  'X-Client_Id': '1177',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
    "https://api.postcodeservice.com/be/v3/houseno-match"
);

let params = {
    "zipcode": "9700",
    "city": "Oudenaarde",
    "street": "Aalststraat",
    "streetid": "970098157329689625",
    "houseno": "2",
    "addon": "A",
    "strict": "0",
    "only_status": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-Secure_Code": "9SRLYBCALURPE2B",
    "X-Client_Id": "1177",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

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

Example response (200, houseno=2, addon=A, strict=0):

{
    "0": {
        "street": "Aalststraat",
        "city": "Oudenaarde",
        "zipcode": 9700,
        "houseno": "2",
        "addon": "A",
        "box": "",
        "streetlang": "nl"
    }
}

Example response (200, houseno=2, addon=, strict=0):


{
    "0": {
        "street": "Aalststraat",
        "city": "Oudenaarde",
        "zipcode": 9700,
        "houseno": "2",
        "addon": "A",
        "box": "",
        "streetlang": "nl"
    },
    "2": {
        "street": "Aalststraat",
        "city": "Oudenaarde",
        "zipcode": 9700,
        "houseno": "2",
        "addon": "B",
        "box": "",
        "streetlang": "nl"
    },
    "3": {
        "street": "Aalststraat",
        "city": "Oudenaarde",
        "zipcode": 9700,
        "houseno": "2",
        "addon": "C",
        "box": "",
        "streetlang": "nl"
    },
}

Example response (200, houseno=2, addon=, strict=1, no match):

{}

Example response (204, houseno=2, addon=, strict=0, only_status=1, matched):

<Empty response>

Example response (418, houseno=2, addon=, strict=1, only_status=1, no match):


{
 <Empty response>
}

Request

GET be/v3/houseno-match

Query Parameters

zipcode  string
a zip code, example: 9700.

city  string
a city name, example: Oudenaarde.

street  string
a street name, example: Aalststraat.

streetid  string optional
Alternative for zipcode, city and street parameters, Can be retrieved with 'street-find' call, example: 970098157329689625.

houseno  string
The house number, example: 2.

addon  string optional
The addon, example: A.

strict  string optional
Default this is turned off and it returns results when houseno is found. When activated it only returns results when houseno + addon combination is met, example 0.

only_status  string optional
Default this is turned off. When active returns no content body only HTTP STATUS 204 when matched, example: 0.

Netherlands API v3

getAddress - Completes a street name

Example request:

curl -X GET \
    -G "https://api.postcodeservice.com/nl/v3/json/getAddress/index.php?postcode=1014BA&huisnummer=37&client_id=1177&secure_code=9SRLYBCALURPE2B" \
    -H "X-Client_Id: 1177" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.postcodeservice.com/nl/v3/json/getAddress/index.php',
    [
        'headers' => [
            'X-Client_Id' => '1177',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'postcode'=> '1014BA',
            'huisnummer'=> '37',
            'client_id'=> '1177',
            'secure_code'=> '9SRLYBCALURPE2B',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://api.postcodeservice.com/nl/v3/json/getAddress/index.php'
params = {
  'postcode': '1014BA',
  'huisnummer': '37',
  'client_id': '1177',
  'secure_code': '9SRLYBCALURPE2B',
}
headers = {
  'X-Client_Id': '1177',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
    "https://api.postcodeservice.com/nl/v3/json/getAddress/index.php"
);

let params = {
    "postcode": "1014BA",
    "huisnummer": "37",
    "client_id": "1177",
    "secure_code": "9SRLYBCALURPE2B",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-Client_Id": "1177",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

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

Example response (200):

{
    "success": true,
    "straatnaam": "Kabelweg",
    "woonplaats": "Amsterdam"
}

Example response (200, Not found, no match):

{
    "success": false,
    "error": "Postcode niet gevonden"
}

Request

GET nl/v3/json/getAddress/index.php

Query Parameters

postcode  string
a valid Dutch zip code, example: 1014BA.

huisnummer  string
a house number, example: 37.

client_id  string
your {YOUR_CLIENT_ID}.

secure_code  string
your secure code {YOUR_AUTH_KEY}.

bash php python javascript