Look up the places of a postal code (tenant:masterdata:read)
GET /api/masterdata/postal-lookup/localities
Module: Master data · operationId: listPostalLocalities · Tag: Postal addresses · Auth: access token (Authorization: Bearer <accessToken>)
Places of a postal code from OpenPLZ (Germany, Austria, Switzerland, Liechtenstein; cached for 24 hours)
with municipality (Gemeinde), county (Kreis/Bezirk) and federal state (Bundesland/Kanton, region as
ISO 3166-2). An unknown postal code answers an empty list, one without the format of its country (DE five
digits, AT, CH, LI four) 400. Other countries answer 400 (country_not_supported); when the lookup is switched off or OpenPLZ is unreachable 503
(unavailable) – enter the place by hand then.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
country |
query | string | ISO 3166-1 alpha-2: DE, AT, CH or LI (default "DE") |
|
postalCode |
query | string | yes | (max length 32) |
Responses
- 200 Places of the postal code (
application/json) - 400 Malformed body or query parameter (
application/json) - 401 Missing, invalid or expired token (empty body)
- 403 The token lacks the permission or carries no tenant (
application/json) - 503 The postal code lookup is switched off or OpenPLZ is unreachable; enter the place by hand (
application/json)
Fields of the 200 answer:
items(array of PostalLocality, required)county(string, required): Kreis (DE) or Bezirk (AT, CH); empty for LIfederalState(string, required): Bundesland or Kanton; empty for LImunicipality(string, required): Gemeindename(string, required): Place (Ort)postalCode(string, required): Postal coderegion(string, required): ISO 3166-2 code of the federal state, as stored in PostalAddress.region; empty for LI
Example 200 answer:
{
"items": [
{
"county": "Berchtesgadener Land",
"federalState": "Bayern",
"municipality": "Schönau a.Königssee",
"name": "Schönau a.Königssee",
"postalCode": "83471",
"region": "DE-BY"
},
{
"county": "Berchtesgadener Land",
"federalState": "Bayern",
"municipality": "Berchtesgaden",
"name": "Berchtesgaden",
"postalCode": "83471",
"region": "DE-BY"
}
]
}
Example request
curl -X GET 'https://api.mbcom.cloud/api/masterdata/postal-lookup/localities?postalCode=80331' \
-H "Authorization: Bearer $ACCESS_TOKEN"