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 multiple cities named "Neuenkirchen", with different `cityAddition` values, such as: "Nordrhein-Westfalen", "Heidekreis" or "Landhagen".

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": 1360,
		"cityAddition": null,
		"postcode": "13469",
		"federalState": "Berlin",
		"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.

federalStateName: string

The name of the federal state ("Land" in German) this city is in.

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.