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
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.
-
houseNumber: