API

AutoComplete.completeHouseNumber

Retrieve a list of house number suggestions for the specified house number. Use the completeStreet method to find the required streetId and postcode parameters.

A Belgian house number may be followed by an additional 'bis number'. The house number and bis number combined identify a street address. Examples include: '1', '1A', '1/30', '2BIS'.

Additionally, a street address might not be complete without a box number representing a mail box or apartment. Box numbers should be preceded by one of the following prefixes: 'bus', 'boite', 'bte', 'box'. Examples of addresses with box numbers: '1 bus 3', '6/3 bte 0101', '18F box A0402'.

URL template

The REST API requires GET requests. Parameters are added to the REST resource URL, and each parameter must be URL-encoded:

https://api.postcode.eu/be/v1/autocomplete/house-number/{streetId}/{postcode}/{language}/{validation}/{houseNumber}

Example REST request

Retrieving /be/v1/autocomplete/house-number/824/2610/nl/none/36 with the proper authentication would use the following HTTP Request:

GET /be/v1/autocomplete/house-number/824/2610/nl/none/36 HTTP/1.1
Host: api.postcode.eu
Authorization: Basic 2eTpkU******…

Example response

The lookup is successful so we receive a 200 OK status in the headers:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

And a JSON response in the body:

[
	{
		"houseNumber": "36 bus 1",
		"number": 36,
		"bisNumber": null,
		"boxNumber": "1",
		"postcode": 2610,
		"status": "validated"
	},
	{
		"houseNumber": "36 bus 2",
		"number": 36,
		"bisNumber": null,
		"boxNumber": "2",
		"postcode": 2610,
		"status": "validated"
	},
	{
		"houseNumber": "36 bus 3",
		"number": 36,
		"bisNumber": null,
		"boxNumber": "3",
		"postcode": 2610,
		"status": "validated"
	},
	{
		"houseNumber": "36 bus 4",
		"number": 36,
		"bisNumber": null,
		"boxNumber": "4",
		"postcode": 2610,
		"status": "validated"
	},
	{
		"houseNumber": "36 bus 5",
		"number": 36,
		"bisNumber": null,
		"boxNumber": "5",
		"postcode": 2610,
		"status": "validated"
	},
	{
		"houseNumber": "36",
		"number": 36,
		"bisNumber": null,
		"boxNumber": null,
		"postcode": 2610,
		"status": "unknown"
	}
]

Parameters

streetId: int

The identifier for the street. Use the streetId output from the completeStreet method.

postcode: int

The postcode from the completeStreet method output. Used as postcode for unknown input number suggestions (see validation parameter). Each validated house number suggestion returned by this method contains a postcode field indicating the correct postcode for that house number. It may differ from the postcode specified in this parameter, as a street can have multiple postcodes.

language: string

The language in which to format the resulting house numbers

validation: string

Determines when an unknown input house number may appear as an 'unknown' suggestion. Possible values: 'strict' - Never; 'street' - When no house numbers are known for the given street; 'number' - As for 'street', or when at least the number part is known; 'none' - Always when the input does not exactly match a known address.

houseNumber: string

The house number, which may include a bis number and/or box number. For example: '38A bus 10'.

Returns

Array of arrays

A list of matching house numbers

houseNumber: string

The complete formatted house number.

number: int

The number part of the house number.

bisNumber: string

The bis number. Maximum length 11, optional. Typically consists of a single letter, a number, or a text such as 'bis'.

boxNumber: string

The box ("bus" / "boite") number. Maximum length 35, optional. Typically consists of digits such as '0103', but can also contain text such as '47 B001' or '3.0'.

postcode: int

The postcode for this house number. Different house numbers on the same street may have different postcodes. Always update the currently selected postcode in your application based on this field.

status: string

Information about the house number match. Possible values: 'validated' - the house number is verified and complete; 'unknown' - the house number does not match a known house number; 'incomplete' - a bis or bus number is needed for a complete address. Call the completeHouseNumber method with the houseNumber parameter from this suggestion for suggestions that are complete.