Postcode API

Germany - Autocomplete a postal area

Get a list of postal areas matching the specified city name or postcode. A city identifier is returned for every match. This identifier can be used as a parameter to the completeStreet method.

The result field `cityAddition` is set to better tell apart cities that have the same name. This can be a municipality name or another type of human readable additional identifier. For example there are three cities named "Berlin", in three different municipalities: "Berlin, Stadt", "M├╝hlenbecker Land" and "Glienicke/Nordbahn".

The result field `postcode` is set when a postcode was matched in the input. It should be used as an additional parameter to the `completeStreet` method in order to narrow down the intended postal area.

The result field `matchedName` is set when a name other than the official city name has been matched. This can be a district or town name inside the matched city. For example the town "Alt Stassow" is a village that is a district of the city "Grammow".

We suggest presenting matches to end users in a format similar to: '{postcode} {cityName} ({matchedName or cityAddition})', where `postcode`, `matchedName` and `cityAddition` are optional depending on the match.

Please note that some postcodes exist in more than one city. An example is postcode 01561, occurring in both cities "Krau├čnitz" and "Lampertswalde".

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/postal-area/{postalArea}

Example REST request

Retrieving /de/v1/autocomplete/postal-area/13469 with the proper authentication would use the following HTTP Request:

GET /de/v1/autocomplete/postal-area/13469 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:

[
	{
		"cityName": "Berlin",
		"cityId": 10380,
		"cityAddition": "Berlin, Stadt",
		"postcode": "13469",
		"matchedName": "13469"
	}
]

Parameters

postalArea: string

Either a postcode or a city name. A city name may be partial or contain spelling errors.

Returns

Array of arrays

An array of matching postal areas

cityName: string

The city name.

cityId: int

Identifier for the matched city. This is the first parameter of the completeStreet method.

cityAddition: string

Optional region name that tells apart cities with the same name. Null if not available or not required.

postcode: string

The postcode, null for matches on city name. A postcode may occur in more than one city. This is the second parameter of the completeStreet method.

matchedName: string

The matched name, may be null. If a city was found based on the name of the city district, this contains the district's name.