Address Autocomplete and Verification API
With the Postcode Service API you can autocomplete a partly given address and check its validity.
Since 2009, our API has been providing vendor-neutral solutions for accurate package delivery and fraud prevention, saving clients millions. It also streamlines address form filling on websites for speed and accuracy. We're committed to delivering high-quality, flexible API services that empower our clients' success.
Premium API
Test credentials are provided below for initial usage. However, a subscription plan is necessary for continued access to this API. Visit postcodeservice.com/#compare-packages to view pricing details and to purchase a subscription.
Additional plugins
For Adobe Magento users, we offer an out-of-the-box solution: the Postcode Service Magento extension. This extension, utilizing the same API, allows for easy and accurate address verification at checkout when using the Magento platform. It's available for download from our GitHub repository at github.com/postcodeservice/postcode-magento2. Our team of experts in Amsterdam develop, support, and maintain this extension to provide seamless integration with the Postcode Service API.
The Dutch company JustBetter has developed an alternative for the default Adobe Magento PWA frontend and integrated the Postcode Service with this frontend. This integration is available for download from their GitHub repository at github.com/rapidez/postcodeservice.
Backwards compatibility policy
Our API follows a strict backwards compatibility policy. New features result in new versions, ensuring your existing implementations remain functional without forced updates or unexpected costs.
For instance,
if you're using the Netherlands endpoint
/nl/v4/find
and we introduce a new version
/nl/v5/find
with new features,
your existing /nl/v5/find
implementation will remain functional.
You have the freedom to decide when to upgrade. Upgrading can provide access to new functions and features, with code adjustments only necessary in certain cases. This policy guarantees our API's stability and supports effective planning of your development resources.
Technical support
You can contact our technical support team via postcodeservice.com/support.
About us
Postcode Service is a trademark of the Total Internet Group B.V.
Authenticating requests
Our API uses authenticated requests. In order to make an authenticated request, add the follow headers along with your API call:
-
X-ClientId
with the value{YOUR_CLIENT_ID}
. -
X-SecureCode
with the value{YOUR_SECURE_CODE}
.
Visit
postcodeservice.com to purchase a subscription plan and obtain your unique
ClientId
and SecureCode
.
Test credentials
You can try our API using the provided credentials below.
Header | Contents |
---|---|
X-ClientId | 1177 |
X-SecureCode | 9SRLYBCALURPE2B |
Please note that these are intended for testing purposes only and may not be used in production environments. These test credentials have limitations, including daily usage limits and added delays, and they may change without prior notice. For production use, please obtain your ClientId and SecureCode by visiting postcodeservice.com and choose a subscription plan.
π³π± Netherlands API
π³π± address-validation - Get address for specified zipcode and house number
requires authentication
This endpoint can be used to validate and fetch full details of an address.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/nl/v6/address-validation?street=Kabelweg&zipcode=1014BA&house_number=21&house_letter=L&house_letter_validation=0&city=Amsterdam&only_status=0&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/nl/v6/address-validation';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street' => 'Kabelweg',
'zipcode' => '1014BA',
'house_number' => '21',
'house_letter' => 'L',
'house_letter_validation' => '0',
'city' => 'Amsterdam',
'only_status' => '0',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/nl/v6/address-validation'
params = {
'street': 'Kabelweg',
'zipcode': '1014BA',
'house_number': '21',
'house_letter': 'L',
'house_letter_validation': '0',
'city': 'Amsterdam',
'only_status': '0',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/nl/v6/address-validation"
);
const params = {
"street": "Kabelweg",
"zipcode": "1014BA",
"house_number": "21",
"house_letter": "L",
"house_letter_validation": "0",
"city": "Amsterdam",
"only_status": "0",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Kabelweg",
"street_language": "nl",
"street_id": "st_4876428982452",
"house_number": 21,
"house_letter": "L",
"house_letter_validated": false,
"zipcode": "1014BA",
"city": "Amsterdam",
"municipality": "Amsterdam",
"province": "Noord-Holland",
"is_po_box": false,
"is_on_wadden_islands": false,
"address_function": [
"accommodation",
"multipurpose",
"office",
"storage"
],
"geo_precision": "rooftop",
"latitude": 52.390515085771,
"longitude": 4.8463724025161,
"postal_address": {
"line_1": "Kabelweg 21L",
"line_2": "1014BA AMSTERDAM",
"line_3": "Netherlands"
}
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"per_page": 10,
"is_last_page": true
}
}
Example response (200, P.O. box):
{
"results": [
{
"street": "Postbus",
"street_language": "nl",
"street_id": null,
"house_number": 1069,
"house_letter": null,
"house_letter_validated": false,
"zipcode": "5602BB",
"city": "Eindhoven",
"municipality": "Eindhoven",
"province": "Noord-Brabant",
"is_po_box": true,
"is_on_wadden_islands": null,
"address_function": [
"unknown"
],
"geo_precision": "geometric_center",
"latitude": 51.4231,
"longitude": 5.4623,
"postal_address": {
"line_1": "Postbus 1069",
"line_2": "5602BB EINDHOVEN",
"line_3": "Netherlands"
}
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"per_page": 10,
"is_last_page": true
}
}
Example response (200, Not found, no match):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (422, house_number contains non-integer characters):
{
"results": [],
"error_code": 422,
"errors": [
{
"error": "The house_number must be an integer",
"error_message": "The house_number must be an integer, so no letters or other characters are allowed. 1A is not allowed, 1 is allowed."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string (UTF-8 encoded) or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
The unique identifier of the whole street. This identifier can be used across other endpoints.
house_number
int|null
The house number of the address or null if unknown
house_letter
string|null
The house letter of the address or null if unknown
house_letter_validated
bool|null
Validation status of house letter: true (validated), false (not validated), or null (validation not applicable).
zipcode
string|null
The zipcode of the address or null if unknown
city
string|null
The city of the address or null if unknown
municipality
string|null
The municipality of the address or null if unknown
province
string|null
The province of the address or null if unknown
is_po_box
bool|null
Indicates whether the address is a post office box (true), not a post office box (false), or if this information is unknown (null)
is_on_wadden_islands
bool|null
Indicates if the address is on a Dutch Wadden Island (true/false) or unknown (null)
address_function
string[]
Contains information about the function of the address which can be one or more of the following: accommodation, detention, education, healthcare, industry, multipurpose, office, residential, shop, sports, storage or unknown
geo_precision
string
Specifies the precision of the geolocation data: approximate, geometric_center, rooftop, range_interpolated or unknown
latitude
float|null
The latitude of the address or null if unknown
longitude
float|null
The longitude of the address or null if unknown
postal_address
object
Contains information about the postal address of the address
error_code
integer|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π³π± address-suggestions - Get address suggestions by partial street name
requires authentication
Often used in combination with the address-streetid endpoint to autocomplete user input and get full details of an address.
This endpoint can be used to provide real-time address suggestions as the user types, enabling autocomplete functionality.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/nl/v6/address-suggestions?street=Kab&city=Amsterdam&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/nl/v6/address-suggestions';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street' => 'Kab',
'city' => 'Amsterdam',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/nl/v6/address-suggestions'
params = {
'street': 'Kab',
'city': 'Amsterdam',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/nl/v6/address-suggestions"
);
const params = {
"street": "Kab",
"city": "Amsterdam",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Kabelgaststraat",
"street_language": "nl",
"street_id": "st_7849419993712442",
"city": "Amsterdam",
"municipality": "Amsterdam",
"province": "Noord-Holland",
"is_on_wadden_islands": false
},
{
"street": "Kabelweg",
"street_language": "nl",
"street_id": "st_4876428982452",
"city": "Amsterdam",
"municipality": "Amsterdam",
"province": "Noord-Holland",
"is_on_wadden_islands": false
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, Not found, no match):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
The street name of the address or null if unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
The unique identifier for the whole street. This identifier can be used across other endpoints.
city
string|null
The city of the address or null if unknown
municipality
string|null
The municipality of the address or null if unknown
province
string|null
The province of the address or null if unknown
is_on_wadden_islands
bool|null
Indicates if the address is on a Dutch Wadden Island (true/false) or unknown (null)
error_code
integer|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π³π± address-streetid - Get address details for specified street_id and house number
requires authentication
Often used in combination with the address-suggestions endpoint to get the remaining details of a complete address.
This endpoint can be used to validate and fetch full details of an address.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/nl/v6/address-streetid?street_id=st_4876428982452&house_number=21&house_letter=L&house_letter_validation=0&only_status=0&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/nl/v6/address-streetid';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street_id' => 'st_4876428982452',
'house_number' => '21',
'house_letter' => 'L',
'house_letter_validation' => '0',
'only_status' => '0',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/nl/v6/address-streetid'
params = {
'street_id': 'st_4876428982452',
'house_number': '21',
'house_letter': 'L',
'house_letter_validation': '0',
'only_status': '0',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/nl/v6/address-streetid"
);
const params = {
"street_id": "st_4876428982452",
"house_number": "21",
"house_letter": "L",
"house_letter_validation": "0",
"only_status": "0",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Kabelweg",
"street_language": "nl",
"street_id": "st_4876428982452",
"house_number": 21,
"house_letter": "L",
"house_letter_validated": false,
"zipcode": "1014BA",
"city": "Amsterdam",
"municipality": "Amsterdam",
"province": "Noord-Holland",
"is_po_box": false,
"is_on_wadden_islands": false,
"address_function": [
"office"
],
"geo_precision": "rooftop",
"latitude": 52.39267104872,
"longitude": 4.8465930696013,
"postal_address": {
"line_1": "Kabelweg 21L",
"line_2": "1014BA AMSTERDAM",
"line_3": "Netherlands"
}
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, Not found, no match):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (422, house_number contains non-integer characters):
{
"results": [],
"error_code": 422,
"errors": [
{
"error": "The house_number must be an integer",
"error_message": "The house_number must be an integer, so no letters or other characters are allowed. 1A is not allowed, 1 is allowed."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string (UTF-8 encoded) or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
The unique identifier of the whole street. This identifier can be used across other endpoints.
house_number
int|null
The house number of the address or null if unknown
house_letter
string|null
The house letter of the address or null if unknown
house_letter_validated
bool|null
Validation status of house number addition: true (validated), false (not validated), or null (validation not applicable).
zipcode
string|null
The zipcode of the address or null if unknown
city
string|null
The city of the address or null if unknown
municipality
string|null
The municipality of the address or null if unknown
province
string|null
The province of the address or null if unknown
is_po_box
bool|null
Indicates whether the address is a post office box (true), not a post office box (false), or if this information is unknown (null)
is_on_wadden_islands
bool|null
Indicates if the address is on a Dutch Wadden Island (true/false) or unknown (null)
address_function
string[]
Contains information about the function of the address which can be one or more of the following: accommodation, detention, education, healthcare, industry, multipurpose, office, residential, shop, sports, storage or unknown
geo_precision
string
Specifies the precision of the geolocation data: approximate, geometric_center, rooftop, range_interpolated or unknown
latitude
float|null
The latitude of the address or null if unknown
longitude
float|null
The longitude of the address or null if unknown
postal_address
object
Contains information about the postal address of the address
error_code
integer|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π³π± address-streetcity - Get address by street, house number and city
requires authentication
This endpoint can be used to validate and fetch full details of an address.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/nl/v6/address-streetcity?street=Kabelweg&house_number=21&house_letter=L&house_letter_validation=0&city=Amsterdam&only_status=0&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/nl/v6/address-streetcity';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street' => 'Kabelweg',
'house_number' => '21',
'house_letter' => 'L',
'house_letter_validation' => '0',
'city' => 'Amsterdam',
'only_status' => '0',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/nl/v6/address-streetcity'
params = {
'street': 'Kabelweg',
'house_number': '21',
'house_letter': 'L',
'house_letter_validation': '0',
'city': 'Amsterdam',
'only_status': '0',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/nl/v6/address-streetcity"
);
const params = {
"street": "Kabelweg",
"house_number": "21",
"house_letter": "L",
"house_letter_validation": "0",
"city": "Amsterdam",
"only_status": "0",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Kabelweg",
"street_language": "nl",
"street_id": "st_4876428982452",
"house_number": 21,
"house_letter": "K",
"house_letter_validated": false,
"zipcode": "1014BA",
"city": "Amsterdam",
"municipality": "Amsterdam",
"province": "Noord-Holland",
"is_po_box": false,
"is_on_wadden_islands": false,
"address_function": [
"office"
],
"geo_precision": "rooftop",
"latitude": 52.39267104872,
"longitude": 4.8465930696013,
"postal_address": {
"line_1": "Kabelweg 21 K",
"line_2": "1014BA AMSTERDAM",
"line_3": "Netherlands"
}
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, Multiple results for rare cases):
{
"results": [
{
"street": "Beatrixstraat",
"street_language": "nl",
"house_number": 1,
"house_letter": null,
"house_letter_validated": false,
"zipcode": "7596KX",
"city": "Rossum",
"municipality": "Dinkelland",
"province": "Overijssel",
"is_postbus": false,
"is_on_wadden_islands": false,
"address_function": [
"residential"
],
"geo_precision": "rooftop",
"latitude": 52.349905438846,
"longitude": 6.9261656920378,
"postal_address": {
"line_1": "Beatrixstraat 1",
"line_2": "7596KX ROSSUM",
"line_3": "Netherlands"
}
},
{
"street": "Beatrixstraat",
"street_language": "nl",
"house_number": 1,
"house_letter": null,
"house_letter_validated": false,
"zipcode": "5328AX",
"city": "Rossum",
"municipality": "Maasdriel",
"province": "Gelderland",
"is_postbus": false,
"is_on_wadden_islands": false,
"address_function": [
"industry"
],
"geo_precision": "rooftop",
"latitude": 51.79898590449,
"longitude": 5.3292603170169,
"postal_address": {
"line_1": "Beatrixstraat 1",
"line_2": "5328AX ROSSUM",
"line_3": "Netherlands"
}
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, Not found, no match):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (422, house_number contains non-integer characters):
{
"results": [],
"error_code": 422,
"errors": [
{
"error": "The house_number must be an integer",
"error_message": "The house_number must be an integer, so no letters or other characters are allowed. 1A is not allowed, 1 is allowed."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
The street name of the address or null if unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
The unique identifier of the whole street. This identifier can be used across other endpoints.
house_number
int|null
The house number of the address or null if unknown
house_letter
string|null
The house letter of the address or null if unknown
house_letter_validated
bool|null
Validation status of house number addition: true (validated), false (not validated), or null (validation not applicable).
zipcode
string|null
The zipcode of the address or null if unknown
city
string|null
The city of the address or null if unknown
municipality
string|null
The municipality of the address or null if unknown
province
string|null
The province of the address or null if unknown
is_po_box
bool|null
Indicates whether the address is a post office box (true), not a post office box (false), or if this information is unknown (null)
is_on_wadden_islands
bool|null
Indicates if the address is on a Dutch Wadden Island (true/false) or unknown (null)
address_function
string[]
Contains information about the function of the address which can be one or more of the following: accommodation, detention, education, healthcare, industry, multipurpose, office, residential, shop, sports, storage or unknown
geo_precision
string
Specifies the precision of the geolocation data: approximate, geometric_center, rooftop, range_interpolated or unknown
latitude
float|null
The latitude of the address or null if unknown
longitude
float|null
The longitude of the address or null if unknown
postal_address
object
Contains information about the postal address of the address
error_code
integer|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π³π± zipcode-find - Returns zipcode and city based on part of a zipcode or part of a city name
requires authentication
This endpoint expects a part of zipcode or city name and will return a list of matches.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/nl/v6/zipcode-find?zipcodezone=1014B&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/nl/v6/zipcode-find';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'zipcodezone' => '1014B',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/nl/v6/zipcode-find'
params = {
'zipcodezone': '1014B',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/nl/v6/zipcode-find"
);
const params = {
"zipcodezone": "1014B",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"zipcode": "1014BA",
"city": "Amsterdam",
"geo_precision": "geometric_center",
"latitude": 52.395165076005,
"longitude": 4.8463242519372
},
{
"zipcode": "1014BB",
"city": "Amsterdam",
"geo_precision": "geometric_center",
"latitude": 52.392131796179,
"longitude": 4.8478134644369
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": false
}
}
Example response (200, No results are found for given zipcode or city name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
zipcode_zones
array|null The numeric part of the zipcode province of the address or null if unknown
city
string|null
The city of the address or null if unknown
geo_precision
string
Returns a string, containing the geo precision of the address
latitude
float|null
Returns a float or null when unknown
longitude
float|null
Returns a float or null when unknown
error_code
integer|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π³π± street-find - Completes the street name based on zipcode and city name
requires authentication
This endpoint needs a correct zipcode, city name and part of a street name. It will return all found matches.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/nl/v6/street-find?zipcode=1014BA&city=Amsterdam&street=Kabel&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/nl/v6/street-find';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'zipcode' => '1014BA',
'city' => 'Amsterdam',
'street' => 'Kabel',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/nl/v6/street-find'
params = {
'zipcode': '1014BA',
'city': 'Amsterdam',
'street': 'Kabel',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/nl/v6/street-find"
);
const params = {
"zipcode": "1014BA",
"city": "Amsterdam",
"street": "Kabel",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Kabelweg",
"street_language": "nl",
"street_id": "st_4876428982452"
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given zipcode, city name and street name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (422, The given zipcode is not valid):
{
"results": [],
"error_code": 422,
"errors": [
{
"error": "Invalid Zipcode",
"error_message": "The zipcode must be 5 digits."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
Returns a string, consisting of a unique 16-character street id
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π³π± zipcode-location - Get location information for specified zipcode
requires authentication
This endpoint can be used to retrieve the longitude and latitude of the geometric center of a zipcode.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/nl/v6/zipcode-location?zipcode=1014BA&only_status=0&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/nl/v6/zipcode-location';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'zipcode' => '1014BA',
'only_status' => '0',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/nl/v6/zipcode-location'
params = {
'zipcode': '1014BA',
'only_status': '0',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/nl/v6/zipcode-location"
);
const params = {
"zipcode": "1014BA",
"only_status": "0",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"zipcode": "1014BA",
"province": "Noord-Holland",
"is_on_wadden_islands": false,
"geo_precision": "geometric_center",
"latitude": 52.395421328766,
"longitude": 4.8463096822221
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, Not found, no match):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (422, Zipcode is not valid):
{
"results": [],
"error_code": 422,
"errors": [
{
"error": "Invalid zipcode format",
"error_message": "Zipcode should conform to the Dutch standard: 4 digits (1000-9999) followed by 2 letters (AA-ZZ)."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array of result objects containing geolocation information
zipcode
string|null
The zipcode of the address or null if unknown
province
string|null
The province of the address or null if unknown
is_on_wadden_islands
bool|null
Indicates if the address is on a Dutch Wadden Island (true/false) or unknown (null)
geo_precision
string
Specifies the precision of the geolocation data: approximate, geometric_center, rooftop, range_interpolated or unknown
latitude
float|null
The latitude of the geometric center of the zipcode or null if unknown
longitude
float|null
The longitude of the geometric center of the zipcode or null if unknown
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π³π± 401-Unauthorized
Returns the error message for unauthorized access.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/nl/v6/401" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: IncorrectSecureCode"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/nl/v6/401';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => 'IncorrectSecureCode',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/nl/v6/401'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': 'IncorrectSecureCode'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/nl/v6/401"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "IncorrectSecureCode",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (401):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 401,
"errors": [
{
"error": "Unauthorized Access",
"error_message": "Unauthorized access V6. Please verify your Client ID and Secure Code. For assistance, contact our support team at support@postcodeservice.com."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π³π± 403-Contract expired
requires authentication
Returns the error message when the contract is expired.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/nl/v6/403" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/nl/v6/403';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/nl/v6/403'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/nl/v6/403"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (403):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 403,
"errors": [
{
"error": "Contract Expired",
"error_message": "Contract expired V6. To continue using our services, visit postcodeservice.com and choose a new subscription plan."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π³π± 429-Rate limiting
requires authentication
A 429 HTTP response indicates too many API calls in a short time.
Default limit: 10 requests/second, sufficient in most cases. Regular responses resume once below this limit. For higher rate limits, contact your account manager at +31 20 218 1024.
This function returns the error message when the request rate is exceeded.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/nl/v6/429" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/nl/v6/429';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/nl/v6/429'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/nl/v6/429"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (429):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 429,
"errors": [
{
"error": "Exceeded request rate limit",
"error_message": "Exceeded request rate limit V6. Please slow down your request rate or increase your limit by contacting your account manager at +31 20 218 1024."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π³π± 500-Server error
requires authentication
Returns the error message when there is a server error.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/nl/v6/500" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/nl/v6/500';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/nl/v6/500'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/nl/v6/500"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (500):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 500,
"errors": [
{
"error": "Internal Server Error",
"error_message": "An unexpected error occurred V6. Please try again later."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π§πͺ Belgium API
π§πͺ address-validation - Get address for specified zipcode, street, house number and city
requires authentication
This endpoint can be used to validate and fetch full details of an address once the user has selected or entered one.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/be/v4/address-validation?street=Aalststraat&house_number=2&house_letter=A&house_letter_validation=0&box=10&zipcode=9700&city=Oudenaarde&only_status=0&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/be/v4/address-validation';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street' => 'Aalststraat',
'house_number' => '2',
'house_letter' => 'A',
'house_letter_validation' => '0',
'box' => '10',
'zipcode' => '9700',
'city' => 'Oudenaarde',
'only_status' => '0',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/be/v4/address-validation'
params = {
'street': 'Aalststraat',
'house_number': '2',
'house_letter': 'A',
'house_letter_validation': '0',
'box': '10',
'zipcode': '9700',
'city': 'Oudenaarde',
'only_status': '0',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/be/v4/address-validation"
);
const params = {
"street": "Aalststraat",
"house_number": "2",
"house_letter": "A",
"house_letter_validation": "0",
"box": "10",
"zipcode": "9700",
"city": "Oudenaarde",
"only_status": "0",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Aalststraat",
"street_language": "nl",
"street_id": "st_970098157329689625",
"house_number": 2,
"house_letter": "A",
"house_letter_validated": false,
"box": "10",
"zipcode": "9700",
"city": "Oudenaarde",
"is_po_box": false,
"address_function": [
"unknown"
],
"geo_precision": "approximate",
"latitude": 50.83610346234,
"longitude": 3.6095554014829,
"postal_address": {
"line_1": "Aalststraat 2A bus 10",
"line_2": "9000 OUDENAARDE",
"line_3": "Belgium"
}
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given street name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string (UTF-8 encoded) or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
Returns a string, consisting of a unique street id (maximum length 16-characters)
house_number
int|null
Returns an integer or null when unknown
house_letter
string|null
Returns a string or null when unknown
house_letter_validated
bool|null
Validation status of house letter: true (validated), false (not validated), or null (validation not applicable).
box
string|null
Returns a string or null when unknown
zipcode
string|null
Returns a string or null when unknown
city
string|null
Returns a string or null when unknown
is_po_box
boolean|null
Returns a boolean or null when unknown
address_function
string[]
Returns an array of address functions, empty if no functions
string
Returns a string, Contains information about the function of the address which can be one or more of the following: accommodation, detention, education, healthcare, industry, multipurpose, office, residential, shop, sports, storage
geo_precision
string
Specifies the precision of the geolocation data: approximate, geometric_center, rooftop, range_interpolated or unknown
latitude
float|null
Returns a float or null when unknown
longitude
float|null
Returns a float or null when unknown
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π§πͺ address-suggestions - Retrieve addresses suggestions by partial street name
requires authentication
Often used in combination with the address-streetid endpoint to autocomplete user input and get full details of an address.
This endpoint can be used to provide real-time address suggestions as the user types, enabling autocomplete functionality.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/be/v4/address-suggestions?street=Koningin+Maria&city=Gent&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/be/v4/address-suggestions';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street' => 'Koningin Maria',
'city' => 'Gent',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/be/v4/address-suggestions'
params = {
'street': 'Koningin Maria',
'city': 'Gent',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/be/v4/address-suggestions"
);
const params = {
"street": "Koningin Maria",
"city": "Gent",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Koningin Maria Hendrikaplein",
"street_language": "nl",
"street_id": "st_900032325761763596",
"zipcode_zone": "9000",
"city": "Gent"
},
{
"street": "Koningin Maria-Hendrikalaan",
"street_language": "nl",
"street_id": "st_119056521757555936",
"zipcode_zone": "1190",
"city": "Vorst"
},
{
"street": "Koningin Maria-Henriettelaan",
"street_language": "nl",
"street_id": "st_397025451615544216",
"zipcode_zone": "3970",
"city": "Leopoldsburg"
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given street name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
Returns a string, consisting of a unique street id (maximum length 16-characters)
zipcode_zone
string|null
Returns a string or null when unknown
city
string|null
Returns a string or null when unknown
is_po_box
boolean|null
Returns a boolean or null when unknown
postal_address
object
Returns an object containing the postal address
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π§πͺ address-streetid - Get address for specified street_id and house number
requires authentication
Often used in combination with the address-suggestions endpoint to get the remaining details of a complete address.
This endpoint can be used to validate and fetch full details of an address once the user has selected or entered one.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/be/v4/address-streetid?street_id=st_970098157329689625&house_number=2&house_letter=A&house_letter_validation=0&box=10&only_status=0&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/be/v4/address-streetid';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street_id' => 'st_970098157329689625',
'house_number' => '2',
'house_letter' => 'A',
'house_letter_validation' => '0',
'box' => '10',
'only_status' => '0',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/be/v4/address-streetid'
params = {
'street_id': 'st_970098157329689625',
'house_number': '2',
'house_letter': 'A',
'house_letter_validation': '0',
'box': '10',
'only_status': '0',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/be/v4/address-streetid"
);
const params = {
"street_id": "st_970098157329689625",
"house_number": "2",
"house_letter": "A",
"house_letter_validation": "0",
"box": "10",
"only_status": "0",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Aalststraat",
"street_language": "nl",
"street_id": "st_970098157329689625",
"house_number": 2,
"house_letter": "A",
"house_letter_validated": false,
"box": "10",
"zipcode": "9700",
"city": "Oudenaarde",
"is_po_box": false,
"address_function": [
"unknown"
],
"geo_precision": "approximate",
"latitude": 50.83610346234,
"longitude": 3.6095554014829,
"postal_address": {
"line_1": "Aalststraat 2A bus 10",
"line_2": "9000 OUDENAARDE",
"line_3": "Belgium"
}
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given street name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string (UTF-8 encoded) or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
Returns a string, consisting of a unique street id (maximum length 16-characters)
house_number
int|null
Returns an integer or null when unknown
house_letter
string|null
Returns a string or null when unknown
house_letter_validated
bool|null
Validation status of house letter: true (validated), false (not validated), or null (validation not applicable).
box
string|null
Returns a string or null when unknown
zipcode
string|null
Returns a string or null when unknown
city
string|null
Returns a string or null when unknown
is_po_box
boolean|null
Returns a boolean or null when unknown
address_function
string[]
Returns an array of address functions, empty if no functions
string
Returns a string, Contains information about the function of the address which can be one or more of the following: accommodation, detention, education, healthcare, industry, multipurpose, office, residential, shop, sports, storage
geo_precision
string
Specifies the precision of the geolocation data: approximate, geometric_center, rooftop, range_interpolated or unknown
latitude
float|null
Returns a float or null when unknown
longitude
float|null
Returns a float or null when unknown
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π§πͺ zipcode-find - Returns zipcode and city based on part of a zipcode or part of a city name
requires authentication
This endpoint expects a part of zipcode or city name and will return a list of matches. Optional settings are available to retrieve city names in one or more specific languages.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/be/v4/zipcode-find?zipcodezone=1050&language=fr&multi_results=0&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/be/v4/zipcode-find';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'zipcodezone' => '1050',
'language' => 'fr',
'multi_results' => '0',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/be/v4/zipcode-find'
params = {
'zipcodezone': '1050',
'language': 'fr',
'multi_results': '0',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/be/v4/zipcode-find"
);
const params = {
"zipcodezone": "1050",
"language": "fr",
"multi_results": "0",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"zipcode": "1050",
"city": "Bruxelles",
"geo_precision": "geometric_center",
"latitude": 50.8222854,
"longitude": 4.3815707
},
{
"zipcode": "1050",
"city": "Ixelles",
"geo_precision": "geometric_center",
"latitude": 50.8222854,
"longitude": 4.3815707
},
{
"zipcode": "1050",
"city": "Saint-Gilles",
"geo_precision": "geometric_center",
"latitude": 50.8222854,
"longitude": 4.3815707
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, multi_results=1):
{
"results": [
{
"city": "Brussel",
"zipcode": "1050",
"geo_precision": "geometric_center",
"latitude": 50.8222854,
"longitude": 4.3815707
},
{
"city": "Bruxelles",
"zipcode": "1050",
"geo_precision": "geometric_center",
"latitude": 50.8222854,
"longitude": 4.3815707
},
{
"city": "Ixelles",
"zipcode": "1050",
"geo_precision": "geometric_center",
"latitude": 50.8222854,
"longitude": 4.3815707
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given zipcode or city name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (422, The multi_results parameter is not valid):
{
"results": [],
"error_code": 422,
"errors": [
{
"error": "Invalid multi_results",
"error_message": "The selected multi_results is invalid."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
zipcode
string|null
Returns a string or null when unknown
city
string|null
Returns a string or null when unknown
geo_precision
string
Specifies the precision of the geolocation data: approximate, geometric_center, rooftop, range_interpolated or unknown
latitude
float|null
Returns a float or null when unknown
longitude
float|null
Returns a float or null when unknown
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π§πͺ street-find - Completes the street name based on zipcode 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 --request GET \
--get "https://api.postcodeservice.com/be/v4/street-find?street=Rue+de+C&zipcode=1040&city=Brussel&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/be/v4/street-find';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street' => 'Rue de C',
'zipcode' => '1040',
'city' => 'Brussel',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/be/v4/street-find'
params = {
'street': 'Rue de C',
'zipcode': '1040',
'city': 'Brussel',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/be/v4/street-find"
);
const params = {
"street": "Rue de C",
"zipcode": "1040",
"city": "Brussel",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Rue de Chambéry",
"street_language": "fr",
"street_id": "st_104077915151295985"
},
{
"street": "Rue de Comines",
"street_language": "fr",
"street_id": "st_104037492375926662"
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given zipcode, city name and street name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (422, The given zipcode is not valid):
{
"results": [],
"error_code": 422,
"errors": [
{
"error": "Invalid Zipcode",
"error_message": "The zipcode must be 4 digits."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string or null when unknown
street_language|null
string
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
Returns a string, consisting of a unique 16-character street id
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π§πͺ houseno-find - Find house numbers and house letters for a given street name
requires authentication
This endpoint expects a zipcode, city name and street name and will return all house numbers and house letters for the street.
Alternatively, you can use the street_id, then this endpoint expects a street_id and will return all the house numbers and house letter for the street.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/be/v4/houseno-find?street=Vliegtuiglaan&street_id=st_900093267659932423&zipcode=9000&city=Gent&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/be/v4/houseno-find';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street' => 'Vliegtuiglaan',
'street_id' => 'st_900093267659932423',
'zipcode' => '9000',
'city' => 'Gent',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/be/v4/houseno-find'
params = {
'street': 'Vliegtuiglaan',
'street_id': 'st_900093267659932423',
'zipcode': '9000',
'city': 'Gent',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/be/v4/houseno-find"
);
const params = {
"street": "Vliegtuiglaan",
"street_id": "st_900093267659932423",
"zipcode": "9000",
"city": "Gent",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Vliegtuiglaan",
"street_language": "nl",
"street_id": "st_900093267659932423",
"house_number": 5,
"house_letter": "",
"zipcode": "9000",
"city": "Gent",
"is_po_box": false,
"address_function": [
"unknown"
],
"geo_precision": "rooftop",
"latitude": 51.0762139660024,
"longitude": 3.743976319518731
},
{
"street": "Vliegtuiglaan",
"street_language": "nl",
"street_id": "st_900093267659932423",
"house_number": 5,
"house_letter": "A",
"zipcode": "9000",
"city": "Gent",
"is_po_box": false,
"address_function": [
"unknown"
],
"geo_precision": "rooftop",
"latitude": 51.076442728654754,
"longitude": 3.743193577395459
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given zipcode, street and city name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (422, The zipcode is not valid):
{
"results": [],
"error_code": 422,
"errors": [
{
"error": "Invalid Zipcode",
"error_message": "The zipcode must be 4 digits."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
Returns a string, consisting of a unique street id (maximum length 16-characters)
house_number
int|null
Returns an integer or null when unknown
house_letter
string|null
Returns a string or null when unknown
zipcode
string|null
Returns a string or null when unknown
city
string|null
Returns a string or null when unknown
geo_precision
string
Specifies the precision of the geolocation data: approximate, geometric_center, rooftop, range_interpolated or unknown
latitude
float|null
Returns a float or null when unknown
longitude
float|null
Returns a float or null when unknown
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π§πͺ houseno-match - Exactly match a house number
requires authentication
This endpoint expects a zipcode, city name and street name, house number and will return if the house number exists.
Alternatively, you can use the street_id, then this endpoint expects a street_id and house number and will return if the house number exists.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/be/v4/houseno-match?street=Aalststraat&street_id=st_970098157329689625&house_number=2&house_letter=A&zipcode=9700&city=Oudenaarde&only_status=0&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/be/v4/houseno-match';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street' => 'Aalststraat',
'street_id' => 'st_970098157329689625',
'house_number' => '2',
'house_letter' => 'A',
'zipcode' => '9700',
'city' => 'Oudenaarde',
'only_status' => '0',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/be/v4/houseno-match'
params = {
'street': 'Aalststraat',
'street_id': 'st_970098157329689625',
'house_number': '2',
'house_letter': 'A',
'zipcode': '9700',
'city': 'Oudenaarde',
'only_status': '0',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/be/v4/houseno-match"
);
const params = {
"street": "Aalststraat",
"street_id": "st_970098157329689625",
"house_number": "2",
"house_letter": "A",
"zipcode": "9700",
"city": "Oudenaarde",
"only_status": "0",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200, house_number=2, house_letter=A, house_letter_validation=0):
{
"results": [
{
"street": "Aalststraat",
"street_language": "nl",
"street_id": "st_970098157329689625",
"house_number": 2,
"house_letter": "A",
"box": "",
"city": "Oudenaarde",
"zipcode": "9700",
"geo_precision": "approximate",
"latitude": 50.836103462329454,
"longitude": 3.609555401482935
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, house_number=2, house_letter=, house_letter_validation=0):
{
"results": [
{
"street": "Aalststraat",
"street_language": "nl",
"street_id": "st_970098157329689625",
"house_number": 2,
"house_letter": "A",
"box": "",
"zipcode": "9700",
"city": "Oudenaarde",
"geo_precision": "approximate",
"latitude": 50.836103462329454,
"longitude": 3.609555401482935
},
{
"street": "Aalststraat",
"street_language": "nl",
"street_id": "st_970098157329689625",
"house_number": 2,
"house_letter": "B",
"box": "",
"zipcode": "9700",
"city": "Oudenaarde",
"geo_precision": "approximate",
"latitude": 50.83624399941114,
"longitude": 3.609739681774569
},
{
"street": "Aalststraat",
"street_language": "nl",
"street_id": "st_970098157329689625",
"house_number": 2,
"house_letter": "C",
"box": "",
"zipcode": "9700",
"city": "Oudenaarde",
"geo_precision": "approximate",
"latitude": 50.83639258854224,
"longitude": 3.6098762734984335
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given zipcode, street, house_number and city name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (204, house_number=2, house_letter=, house_letter_validation=0, only_status=1, matched):
Empty response
Example response (418, house_number=2, house_letter=F, house_letter_validation=1, only_status=1, no match):
{}
Example response (422, The zipcode is not valid):
{
"results": [],
"error_code": 422,
"errors": [
{
"error": "Invalid Zipcode",
"error_message": "The zipcode must be 4 digits."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (422, The house_letter_validation parameter is not valid):
{
"results": [],
"error_code": 422,
"errors": [
{
"error": "The selected house_letter_validation is invalid",
"error_message": "The selected house_letter_validation is invalid."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
Returns a string, consisting of a unique 16-character street id
house_number
int|null
Returns an integer or null when unknown
house_letter
string|null
Returns a string or null when unknown
box
string|null
Returns a string or null when unknown
zipcode
string|null
Returns a string or null when unknown
city
string|null
Returns a string or null when unknown
geo_precision
string
Specifies the precision of the geolocation data: approximate, geometric_center, rooftop, range_interpolated or unknown
latitude
float|null
Returns a float or null when unknown
longitude
float|null
Returns a float or null when unknown
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π§πͺ 401-Unauthorized
Returns the error message for unauthorized access.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/be/v4/401" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: IncorrectSecureCode"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/be/v4/401';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => 'IncorrectSecureCode',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/be/v4/401'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': 'IncorrectSecureCode'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/be/v4/401"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "IncorrectSecureCode",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (401):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 401,
"errors": [
{
"error": "Unauthorized Access",
"error_message": "Unauthorized access V4. Please verify your Client ID and Secure Code. For assistance, contact our support team at support@postcodeservice.com."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π§πͺ 403-Contract expired
requires authentication
Returns the error message when the contract is expired.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/be/v4/403" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/be/v4/403';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/be/v4/403'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/be/v4/403"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (403):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 403,
"errors": [
{
"error": "Contract Expired",
"error_message": "Contract expired V4. To continue using our services, visit postcodeservice.com and choose a new subscription plan."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π§πͺ 429-Rate limiting
requires authentication
A 429 HTTP response indicates too many API calls in a short time.
Default limit: 10 requests/second, sufficient in most cases. Regular responses resume once below this limit. For higher rate limits, contact your account manager at +31 20 218 1024.
This function returns the error message when the request rate is exceeded.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/be/v4/429" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/be/v4/429';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/be/v4/429'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/be/v4/429"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (429):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 429,
"errors": [
{
"error": "Exceeded request rate limit",
"error_message": "Exceeded request rate limit V4. Please slow down your request rate or increase your limit by contacting your account manager at +31 20 218 1024."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π§πͺ 500-Server error
requires authentication
Returns the error message when there is a server error.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/be/v4/500" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/be/v4/500';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/be/v4/500'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/be/v4/500"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (500):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 500,
"errors": [
{
"error": "Internal Server Error",
"error_message": "An unexpected error occurred V4. Please try again later."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π©πͺ Germany API
π©πͺ address-validation - Get address for specified zipcode, street and house number
requires authentication
This endpoint can be used to validate and fetch full details of an address once the user has selected or entered one.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/de/v2/address-validation?street=Tucherweg&house_number=48&house_letter=A&house_letter_validation=0&house_number_addition=treppe+1&zipcode=40724&city=Hilden&only_status=0&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/de/v2/address-validation';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street' => 'Tucherweg',
'house_number' => '48',
'house_letter' => 'A',
'house_letter_validation' => '0',
'house_number_addition' => 'treppe 1',
'zipcode' => '40724',
'city' => 'Hilden',
'only_status' => '0',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/de/v2/address-validation'
params = {
'street': 'Tucherweg',
'house_number': '48',
'house_letter': 'A',
'house_letter_validation': '0',
'house_number_addition': 'treppe 1',
'zipcode': '40724',
'city': 'Hilden',
'only_status': '0',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/de/v2/address-validation"
);
const params = {
"street": "Tucherweg",
"house_number": "48",
"house_letter": "A",
"house_letter_validation": "0",
"house_number_addition": "treppe 1",
"zipcode": "40724",
"city": "Hilden",
"only_status": "0",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Tucherweg",
"street_language": "de",
"street_id": "st_407247266946847986",
"house_number": 48,
"house_letter": "A",
"house_letter_validated": false,
"house_number_addition": "treppe 1",
"zipcode": "40724",
"city": "Hilden",
"is_po_box": false,
"address_function": [
"unknown"
],
"geo_precision": "rooftop",
"latitude": 51.1722206,
"longitude": 6.9403854,
"postal_address": {
"line_1": "Tucherweg 48A treppe 1",
"line_2": "40724 HILDEN",
"line_3": "Germany"
}
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given street):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string (UTF-8 encoded) or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
Returns a string, consisting of a unique 16-character street id
house_number
int|null
Returns an integer or null when unknown
house_letter
string|null
Returns a string or null when unknown
house_letter_validated
bool|null
Validation status of house letter: true (validated), false (not validated), or null (validation not applicable).
house_number_addition
string|null
Returns a string or null when unknown
zipcode
string|null
Returns a string or null when unknown
city
string|null
Returns a string or null when unknown
is_po_box
boolean
Returns true if the address is a PO box, false otherwise
address_function
string[]
Returns an array of strings, containing the address function(s) of the address
geo_precision
string
Returns a string, containing the geo precision of the address
latitude
float|null
Returns a float or null when unknown
longitude
float|null
Returns a float or null when unknown
postal_address
object
Returns an object containing the postal address
line_1
string
Returns a string, containing the first line of the postal address
line_2
string
Returns a string, containing the second line of the postal address
line_3
string
Returns a string, containing the third line of the postal address
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π©πͺ address-suggestions - Retrieve full addresses by partial street name
requires authentication
Often used in combination with the address-streetid endpoint to autocomplete user input and get full details of an address.
This endpoint can be used to provide real-time address suggestions as the user types, enabling autocomplete functionality.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/de/v2/address-suggestions?street=Marbacher&city=Amt&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/de/v2/address-suggestions';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street' => 'Marbacher',
'city' => 'Amt',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/de/v2/address-suggestions'
params = {
'street': 'Marbacher',
'city': 'Amt',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/de/v2/address-suggestions"
);
const params = {
"street": "Marbacher",
"city": "Amt",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Marbacher Berg",
"street_language": "de",
"street_id": "st_993342231655576189",
"zipcode": "99334",
"city": "Amt Wachsenburg"
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given street):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string or null when unknown
street_id
string
Returns a string, consisting of a unique 16-character street id
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
zipcode
string|null
Returns a string or null when unknown
city
string|null
Returns a string or null when unknown
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π©πͺ address-streetid - Get address for specified street_id and house number
requires authentication
Often used in combination with the address-suggestions endpoint to get the remaining details of a complete address.
This endpoint can be used to validate and fetch full details of an address once the user has selected or entered one.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/de/v2/address-streetid?street_id=st_407247266946847986&house_number=48&house_letter=A&house_letter_validation=0&house_number_addition=treppe+1&only_status=0&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/de/v2/address-streetid';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street_id' => 'st_407247266946847986',
'house_number' => '48',
'house_letter' => 'A',
'house_letter_validation' => '0',
'house_number_addition' => 'treppe 1',
'only_status' => '0',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/de/v2/address-streetid'
params = {
'street_id': 'st_407247266946847986',
'house_number': '48',
'house_letter': 'A',
'house_letter_validation': '0',
'house_number_addition': 'treppe 1',
'only_status': '0',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/de/v2/address-streetid"
);
const params = {
"street_id": "st_407247266946847986",
"house_number": "48",
"house_letter": "A",
"house_letter_validation": "0",
"house_number_addition": "treppe 1",
"only_status": "0",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Tucherweg",
"street_language": "de",
"street_id": "st_407247266946847986",
"house_number": 48,
"house_letter": "A",
"house_letter_validated": false,
"house_number_addition": "treppe 1",
"zipcode": "40724",
"city": "Hilden",
"is_po_box": false,
"address_function": [
"unknown"
],
"geo_precision": "rooftop",
"latitude": 51.1722206,
"longitude": 6.9403854,
"postal_address": {
"line_1": "Tucherweg 48A treppe 1",
"line_2": "40724 HILDEN",
"line_3": "Germany"
}
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given street):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string (UTF-8 encoded) or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
Returns a string, consisting of a unique 16-character street id
house_number
int|null
Returns an integer or null when unknown
house_letter
string|null
Returns a string or null when unknown
house_number_addition
string|null
Returns a string or null when unknown
zipcode
string|null
Returns a string or null when unknown
city
string|null
Returns a string or null when unknown
is_po_box
boolean
Returns true if the address is a PO box, false otherwise
address_function
string[]
Returns an array of strings, containing the address function(s) of the address
geo_precision
string
Returns a string, containing the geo precision of the address
latitude
float|null
Returns a float or null when unknown
longitude
float|null
Returns a float or null when unknown
postal_address
object
Returns an object containing the postal address
line_1
string
Returns a string, containing the first line of the postal address
line_2
string
Returns a string, containing the second line of the postal address
line_3
string
Returns a string, containing the third line of the postal address
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π©πͺ zipcode-find - Returns zipcode and city based on part of a zipcode or part of a city name
requires authentication
This endpoint expects a part of zipcode or city name and will return a list of matches.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/de/v2/zipcode-find?zipcodezone=4072&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/de/v2/zipcode-find';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'zipcodezone' => '4072',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/de/v2/zipcode-find'
params = {
'zipcodezone': '4072',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/de/v2/zipcode-find"
);
const params = {
"zipcodezone": "4072",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"zipcode": "40721",
"city": "Düsseldorf",
"geo_precision": "geometric_center",
"latitude": 51.213312474303,
"longitude": 6.8111261632268
},
{
"zipcode": "40721",
"city": "Hilden",
"geo_precision": "geometric_center",
"latitude": 51.171760972964,
"longitude": 6.9349326729642
},
{
"zipcode": "40723",
"city": "Hilden",
"geo_precision": "geometric_center",
"latitude": 51.171760972964,
"longitude": 6.9349326729642
},
{
"zipcode": "40724",
"city": "Hilden",
"geo_precision": "geometric_center",
"latitude": 51.171760972964,
"longitude": 6.9349326729642
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given zipcode or city name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
zipcode_zones
array|null The numeric part of the zipcode province of the address or null if unknown
city
string|null
The city of the address or null if unknown
geo_precision
string
Returns a string, containing the geo precision of the address
latitude
float|null
Returns a float or null when unknown
longitude
float|null
Returns a float or null when unknown
error_code
integer|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π©πͺ street-find - Completes the street name based on zipcode and city name
requires authentication
This endpoint needs a correct zipcode, city name and part of a street name. It will return all found matches.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/de/v2/street-find?zipcode=40724&city=Hilden&street=Ka&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/de/v2/street-find';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'zipcode' => '40724',
'city' => 'Hilden',
'street' => 'Ka',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/de/v2/street-find'
params = {
'zipcode': '40724',
'city': 'Hilden',
'street': 'Ka',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/de/v2/street-find"
);
const params = {
"zipcode": "40724",
"city": "Hilden",
"street": "Ka",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Kalstert",
"street_language": "de",
"street_id": "st_407247266946847986"
},
{
"street": "Karlrobert-Kreiten-Straße",
"street_language": "de",
"street_id": "st_407248987927323392"
},
{
"street": "Käthe-Kollwitz-Weg",
"street_language": "de",
"street_id": "st_407249782892152973"
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given zipcode, city name and street name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (422, The given zipcode is not valid):
{
"results": [],
"error_code": 422,
"errors": [
{
"error": "Invalid Zipcode",
"error_message": "The zipcode must be 5 digits."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
Returns a string, consisting of a unique 16-character street id
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π©πͺ houseno-find - Find house numbers and house letters for a given street name
requires authentication
This endpoint expects a zipcode, city name and street name and will return all house numbers and house letters for the street.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/de/v2/houseno-find?zipcode=40724&city=Hilden&street=Kalstert&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/de/v2/houseno-find';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'zipcode' => '40724',
'city' => 'Hilden',
'street' => 'Kalstert',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/de/v2/houseno-find'
params = {
'zipcode': '40724',
'city': 'Hilden',
'street': 'Kalstert',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/de/v2/houseno-find"
);
const params = {
"zipcode": "40724",
"city": "Hilden",
"street": "Kalstert",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Kalstert",
"street_language": "de",
"street_id": "st_407247266946847986",
"house_number": 1,
"house_letter": "",
"zipcode": "40724",
"city": "Hilden",
"is_po_box": false,
"address_function": [
"unknown"
],
"geo_precision": "unknown",
"latitude": null,
"longitude": null
},
{
"street": "Kalstert",
"street_language": "de",
"street_id": "st_407247266946847986",
"house_number": 104,
"house_letter": "",
"zipcode": "40724",
"city": "Hilden",
"is_po_box": false,
"address_function": [
"unknown"
],
"geo_precision": "unknown",
"latitude": null,
"longitude": null
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given zipcode, city name and street name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (422, The given zipcode is not valid):
{
"results": [],
"error_code": 422,
"errors": [
{
"error": "Invalid Zipcode",
"error_message": "The zipcode must be 5 digits."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
Returns a string, consisting of a unique 16-character street id
house_number
int|null
Returns an integer or null when unknown
house_letter
string|null
Returns a string or null when unknown
box
string|null
Returns a string or null when unknown
zipcode
string|null
Returns a string or null when unknown
city
string|null
Returns a string or null when unknown
is_po_box
boolean
Returns true if the address is a PO box, false otherwise
address_function
string[]
Returns an array of strings, containing the address function(s) of the address
geo_precision
string
Returns a string, containing the geo precision of the address
latitude
float|null
Returns a float or null when unknown
longitude
float|null
Returns a float or null when unknown
postal_address
object
Returns an object containing the postal address
line_1
string
Returns a string, containing the first line of the postal address
line_2
string
Returns a string, containing the second line of the postal address
line_3
string
Returns a string, containing the third line of the postal address
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π©πͺ houseno-match - Exactly match a house number
requires authentication
This endpoint expects a zipcode, city name and street name, house number and will return if the house number exists.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/de/v2/houseno-match?street=Tucherweg&house_number=48&house_letter=A&zipcode=40724&city=Hilden&only_status=0&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/de/v2/houseno-match';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street' => 'Tucherweg',
'house_number' => '48',
'house_letter' => 'A',
'zipcode' => '40724',
'city' => 'Hilden',
'only_status' => '0',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/de/v2/houseno-match'
params = {
'street': 'Tucherweg',
'house_number': '48',
'house_letter': 'A',
'zipcode': '40724',
'city': 'Hilden',
'only_status': '0',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/de/v2/houseno-match"
);
const params = {
"street": "Tucherweg",
"house_number": "48",
"house_letter": "A",
"zipcode": "40724",
"city": "Hilden",
"only_status": "0",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200, house_number=48, house_letter=A):
{
"results": [
{
"street": "Tucherweg",
"street_language": "de",
"street_id": "st_407247266946847986",
"house_number": 48,
"house_letter": "A",
"zipcode": "40724",
"city": "Hilden",
"geo_precision": "rooftop",
"latitude": 51.1722315,
"longitude": 6.9402763
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, house_number=48, house_letter=):
{
"results": [
{
"street": "Tucherweg",
"street_language": "de",
"street_id": "st_407247266946847986",
"house_number": 48,
"house_letter": "",
"zipcode": "40724",
"city": "Hilden",
"geo_precision": "rooftop",
"latitude": 51.1722315,
"longitude": 6.9402763
},
{
"street": "Tucherweg",
"street_language": "de",
"street_id": "st_407247266946847986",
"house_number": 48,
"house_letter": "A",
"zipcode": "40724",
"city": "Hilden",
"geo_precision": "rooftop",
"latitude": 51.1722315,
"longitude": 6.9402763
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given zipcode, city name and street name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, house_number=48, house_letter=B, no match):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (204, house_number=48, house_letter=, only_status=1, matched):
Empty response
Example response (418, house_number=48, house_letter=B, only_status=1, no match):
"
"
Example response (422, The given zipcode is not valid):
{
"results": [],
"error_code": 422,
"errors": [
{
"error": "Invalid Zipcode",
"error_message": "The zipcode must be 5 digits."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
house_number
int|null
Returns an integer or null when unknown
house_letter
string|null
Returns a string or null when unknown
house_letter_validated
bool|null
Validation status of house number addition: true (validated), false (not validated), or null (validation not applicable).
zipcode
string|null
Returns a string or null when unknown
city
string|null
Returns a string or null when unknown
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π©πͺ 401-Unauthorized
Returns the error message for unauthorized access.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/de/v2/401" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: IncorrectSecureCode"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/de/v2/401';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => 'IncorrectSecureCode',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/de/v2/401'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': 'IncorrectSecureCode'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/de/v2/401"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "IncorrectSecureCode",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (401):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 401,
"errors": [
{
"error": "Unauthorized Access",
"error_message": "Unauthorized access V2. Please verify your Client ID and Secure Code. For assistance, contact our support team at support@postcodeservice.com."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π©πͺ 403-Contract expired
requires authentication
Returns the error message when the contract is expired.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/de/v2/403" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/de/v2/403';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/de/v2/403'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/de/v2/403"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (403):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 403,
"errors": [
{
"error": "Contract Expired",
"error_message": "Contract expired V2. To continue using our services, visit postcodeservice.com and choose a new subscription plan."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π©πͺ 429-Rate limiting
requires authentication
A 429 HTTP response indicates too many API calls in a short time.
Default limit: 10 requests/second, sufficient in most cases. Regular responses resume once below this limit. For higher rate limits, contact your account manager at +31 20 218 1024.
This function returns the error message when the request rate is exceeded.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/de/v2/429" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/de/v2/429';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/de/v2/429'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/de/v2/429"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (429):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 429,
"errors": [
{
"error": "Exceeded request rate limit",
"error_message": "Exceeded request rate limit V2. Please slow down your request rate or increase your limit by contacting your account manager at +31 20 218 1024."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π©πͺ 500-Server error
requires authentication
Returns the error message when there is a server error.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/de/v2/500" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/de/v2/500';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/de/v2/500'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/de/v2/500"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (500):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 500,
"errors": [
{
"error": "Internal Server Error",
"error_message": "An unexpected error occurred V2. Please try again later."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π«π· French API
π«π· address-validation - Get address for specified zipcode, street and house number
requires authentication
This endpoint can be used to validate and fetch full details of an address once the user has selected or entered one.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/fr/v1/address-validation?street=All%C3%A9e+de+Challes&house_number=1&house_letter=bis&house_letter_validation=0&zipcode=01000&city=Bourg-en-Bresse&only_status=0&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/fr/v1/address-validation';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street' => 'AllΓ©e de Challes',
'house_number' => '1',
'house_letter' => 'bis',
'house_letter_validation' => '0',
'zipcode' => '01000',
'city' => 'Bourg-en-Bresse',
'only_status' => '0',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/fr/v1/address-validation'
params = {
'street': 'AllΓ©e de Challes',
'house_number': '1',
'house_letter': 'bis',
'house_letter_validation': '0',
'zipcode': '01000',
'city': 'Bourg-en-Bresse',
'only_status': '0',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/fr/v1/address-validation"
);
const params = {
"street": "AllΓ©e de Challes",
"house_number": "1",
"house_letter": "bis",
"house_letter_validation": "0",
"zipcode": "01000",
"city": "Bourg-en-Bresse",
"only_status": "0",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Allée de Challes",
"street_language": "fr",
"street_id": "st_10002655321896665",
"house_number": 1,
"house_letter": "bis",
"house_letter_validated": false,
"zipcode": "01000",
"city": "Bourg-en-Bresse",
"is_po_box": false,
"address_function": [
"unknown"
],
"geo_precision": "rooftop",
"latitude": 46.205877,
"longitude": 5.230158,
"postal_address": {
"line_1": "1bis Allée de Challes",
"line_2": "01000 BOURG-EN-BRESSE",
"line_3": "France"
}
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given street):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string (UTF-8 encoded) or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
Returns a string, consisting of a unique 16-character street id
house_number
int|null
Returns an integer or null when unknown
house_letter
string|null
Returns a string or null when unknown
house_letter_validated
bool|null
Validation status of house letter: true (validated), false (not validated), or null (validation not applicable).
zipcode
string|null
Returns a string or null when unknown
city
string|null
Returns a string or null when unknown
is_po_box
boolean
Returns true if the address is a PO box, false otherwise
address_function
string[]
Returns an array of strings, containing the address function(s) of the address
geo_precision
string
Returns a string, containing the geo precision of the address
latitude
float|null
Returns a float or null when unknown
longitude
float|null
Returns a float or null when unknown
postal_address
object
Returns an object containing the postal address
line_1
string
Returns a string, containing the first line of the postal address
line_2
string
Returns a string, containing the second line of the postal address
line_3
string
Returns a string, containing the third line of the postal address
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π«π· address-suggestions - Retrieve full addresses by partial street name
requires authentication
Often used in combination with the address-streetid endpoint to autocomplete user input and get full details of an address.
This endpoint can be used to provide real-time address suggestions as the user types, enabling autocomplete functionality.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/fr/v1/address-suggestions?street=All%C3%A9e+Jean+Bal&city=Yvrac&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/fr/v1/address-suggestions';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street' => 'AllΓ©e Jean Bal',
'city' => 'Yvrac',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/fr/v1/address-suggestions'
params = {
'street': 'AllΓ©e Jean Bal',
'city': 'Yvrac',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/fr/v1/address-suggestions"
);
const params = {
"street": "AllΓ©e Jean Bal",
"city": "Yvrac",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Allee Jean Balade",
"street_language": "fr",
"street_id": "st_993342231655576189",
"zipcode": "33370",
"city": "Yvrac"
},
{
"street": "Allée Jean Balde",
"street_language": "fr",
"street_id": "st_990928511797344426",
"zipcode": "33120",
"city": "Arcachon"
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given street):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string or null when unknown
street_id
string
Returns a string, consisting of a unique 16-character street id
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
zipcode
string|null
Returns a string or null when unknown
city
string|null
Returns a string or null when unknown
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π«π· address-streetid - Get address for specified street_id and house number
requires authentication
Often used in combination with the address-suggestions endpoint to get the remaining details of a complete address.
This endpoint can be used to validate and fetch full details of an address once the user has selected or entered one.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/fr/v1/address-streetid?street_id=st_10002655321896665&house_number=1&house_letter=bis&house_letter_validation=0&only_status=0&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/fr/v1/address-streetid';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'street_id' => 'st_10002655321896665',
'house_number' => '1',
'house_letter' => 'bis',
'house_letter_validation' => '0',
'only_status' => '0',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/fr/v1/address-streetid'
params = {
'street_id': 'st_10002655321896665',
'house_number': '1',
'house_letter': 'bis',
'house_letter_validation': '0',
'only_status': '0',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/fr/v1/address-streetid"
);
const params = {
"street_id": "st_10002655321896665",
"house_number": "1",
"house_letter": "bis",
"house_letter_validation": "0",
"only_status": "0",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Allée de Challes",
"street_language": "fr",
"street_id": "st_10002655321896665",
"house_number": 1,
"house_letter": "bis",
"house_letter_validated": false,
"zipcode": "01000",
"city": "Bourg-en-Bresse",
"is_po_box": false,
"address_function": [
"unknown"
],
"geo_precision": "rooftop",
"latitude": 46.205877,
"longitude": 5.230158,
"postal_address": {
"line_1": "1bis Allée de Challes",
"line_2": "01000 BOURG-EN-BRESSE",
"line_3": "France"
}
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given street):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string (UTF-8 encoded) or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
Returns a string, consisting of a unique 16-character street id
house_number
int|null
Returns an integer or null when unknown
house_letter
string|null
Returns a string or null when unknown
house_letter_validated
bool|null
Validation status of house letter: true (validated), false (not validated), or null (validation not applicable).
zipcode
string|null
Returns a string or null when unknown
city
string|null
Returns a string or null when unknown
is_po_box
boolean
Returns true if the address is a PO box, false otherwise
address_function
string[]
Returns an array of strings, containing the address function(s) of the address
geo_precision
string
Returns a string, containing the geo precision of the address
latitude
float|null
Returns a float or null when unknown
longitude
float|null
Returns a float or null when unknown
postal_address
object
Returns an object containing the postal address
line_1
string
Returns a string, containing the first line of the postal address
line_2
string
Returns a string, containing the second line of the postal address
line_3
string
Returns a string, containing the third line of the postal address
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π«π· zipcode-find - Returns zipcode and city based on part of a zipcode or part of a city name
requires authentication
This endpoint expects a part of zipcode or city name and will return a list of matches.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/fr/v1/zipcode-find?zipcodezone=0100&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/fr/v1/zipcode-find';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'zipcodezone' => '0100',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/fr/v1/zipcode-find'
params = {
'zipcodezone': '0100',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/fr/v1/zipcode-find"
);
const params = {
"zipcodezone": "0100",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"zipcode": "01000",
"city": "Bourg-en-Bresse",
"geo_precision": "geometric_center",
"latitude": 46.202836199928,
"longitude": 5.23269573883
},
{
"zipcode": "01000",
"city": "Saint-Denis-lès-Bourg",
"geo_precision": "geometric_center",
"latitude": 46.202687320372,
"longitude": 5.1976543021978
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given zipcode or city name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
zipcode_zones
array|null The numeric part of the zipcode province of the address or null if unknown
city
string|null
The city of the address or null if unknown
geo_precision
string
Returns a string, containing the geo precision of the address
latitude
float|null
Returns a float or null when unknown
longitude
float|null
Returns a float or null when unknown
error_code
integer|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π«π· street-find - Completes the street name based on zipcode and city name
requires authentication
This endpoint needs a correct zipcode, city name and part of a street name. It will return all found matches.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/fr/v1/street-find?zipcode=01000&city=Bourg-en-Bresse&street=All%C3%A9e+Bi%C3%A8&page=1&page_limit=10" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/fr/v1/street-find';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
'query' => [
'zipcode' => '01000',
'city' => 'Bourg-en-Bresse',
'street' => 'Allée Biè',
'page' => '1',
'page_limit' => '10',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/fr/v1/street-find'
params = {
'zipcode': '01000',
'city': 'Bourg-en-Bresse',
'street': 'Allée Biè',
'page': '1',
'page_limit': '10',
}
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
const url = new URL(
"https://api.postcodeservice.com/fr/v1/street-find"
);
const params = {
"zipcode": "01000",
"city": "Bourg-en-Bresse",
"street": "Allée Biè",
"page": "1",
"page_limit": "10",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"results": [
{
"street": "Allée Bièvre",
"street_language": "fr",
"street_id": "st_10009533927221583"
}
],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (200, No results are found for given zipcode, city name and street name):
{
"results": [],
"error_code": null,
"errors": [],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Example response (422, The given zipcode is not valid):
{
"results": [],
"error_code": 422,
"errors": [
{
"error": "Invalid Zipcode",
"error_message": "The zipcode must be 5 digits."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 10,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An array containing the results, empty if no results. More details
street
string|null
Returns a string or null when unknown
street_language
string|null
The language of the street name in ISO 639-1 format, or null if unknown
street_id
string
Returns a string, consisting of a unique 16-character street id
error_code
string|null
Returns the error code if there is an error, null otherwise
errors
string[]
An array of error messages, empty if no errors. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π«π· 401-Unauthorized
Returns the error message for unauthorized access.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/fr/v1/401" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: IncorrectSecureCode"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/fr/v1/401';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => 'IncorrectSecureCode',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/fr/v1/401'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': 'IncorrectSecureCode'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/fr/v1/401"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "IncorrectSecureCode",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (401):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 401,
"errors": [
{
"error": "Unauthorized Access",
"error_message": "Unauthorized access V1. Please verify your Client ID and Secure Code. For assistance, contact our support team at support@postcodeservice.com."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π«π· 403-Contract expired
requires authentication
Returns the error message when the contract is expired.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/fr/v1/403" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/fr/v1/403';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/fr/v1/403'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/fr/v1/403"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (403):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 403,
"errors": [
{
"error": "Contract Expired",
"error_message": "Contract expired V1. To continue using our services, visit postcodeservice.com and choose a new subscription plan."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π«π· 429-Rate limiting
requires authentication
A 429 HTTP response indicates too many API calls in a short time.
Default limit: 10 requests/second, sufficient in most cases. Regular responses resume once below this limit. For higher rate limits, contact your account manager at +31 20 218 1024.
This function returns the error message when the request rate is exceeded.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/fr/v1/429" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/fr/v1/429';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/fr/v1/429'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/fr/v1/429"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (429):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 429,
"errors": [
{
"error": "Exceeded request rate limit",
"error_message": "Exceeded request rate limit V1. Please slow down your request rate or increase your limit by contacting your account manager at +31 20 218 1024."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not
π«π· 500-Server error
requires authentication
Returns the error message when there is a server error.
Example request:
curl --request GET \
--get "https://api.postcodeservice.com/fr/v1/500" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-ClientId: 1177" \
--header "X-SecureCode: 9SRLYBCALURPE2B"
$client = new \GuzzleHttp\Client();
$url = 'https://api.postcodeservice.com/fr/v1/500';
$response = $client->get(
$url,
[
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-ClientId' => '1177',
'X-SecureCode' => '9SRLYBCALURPE2B',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json
url = 'https://api.postcodeservice.com/fr/v1/500'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-ClientId': '1177',
'X-SecureCode': '9SRLYBCALURPE2B'
}
response = requests.request('GET', url, headers=headers)
response.json()
const url = new URL(
"https://api.postcodeservice.com/fr/v1/500"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-ClientId": "1177",
"X-SecureCode": "9SRLYBCALURPE2B",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (500):
Show headers
cache-control: no-cache, private
content-type: application/json
{
"results": [],
"error_code": 500,
"errors": [
{
"error": "Internal Server Error",
"error_message": "An unexpected error occurred V1. Please try again later."
}
],
"pagination": {
"current_page": 1,
"results_per_page": 0,
"is_last_page": true
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Response
Response Fields
results
string[]
An empty array as there are no results for an error
errors
string[]
An array of error messages. More details
error
string
A brief description of the error
error_message
string
A detailed description of the error
pagination
object
Contains information about the pagination of the results. More details
current_page
integer
The number of the current page
results_per_page
integer
The number of results displayed per page
is_last_page
boolean
Whether this is the last page or not