Germany - Autocomplete a house number within a street

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 German house number may be followed by an addition. The house number and house number addition combined identify a street address. Examples include: '1', '1A', '1-30'.

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/de/v1/autocomplete/house-number/{cityId}/{streetId}/{postcode}/{validation}/{houseNumber}

Example REST request

Retrieving /de/v1/autocomplete/house-number/21295627/272091/12610/none/36 with the proper authentication would use the following HTTP Request:

GET /de/v1/autocomplete/house-number/21295627/272091/12610/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",
		"number": 36,
		"addition": null,
		"postcode": "02610",
		"status": "validated"
	},
	{
		"houseNumber": "36-2",
		"number": 36,
		"addition": "2",
		"postcode": "02610",
		"status": "validated"
	}
]

Parameters

cityId: int or null: Identifier for the city in which the street is located. Use the cityId from the completePostalArea method.
streetId: int: The identifier for the street. Use the streetId output from the completeStreet method.
postcode: string: 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.
validation: string: Determines when an unknown input house number may appear as an 'unknown' suggestion. Possible values: 'strict' - Never; 'number' - 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 an addition. For example: '38-52'.

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.
addition: string or null: A house number addition. Maximum length 8, optional.
postcode: string: 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' - an addition is needed for a complete address. Call the completeHouseNumber method with the houseNumber parameter from this suggestion for suggestions that are complete.