ConnectCloud Developers

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 LI
    • federalState (string, required): Bundesland or Kanton; empty for LI
    • municipality (string, required): Gemeinde
    • name (string, required): Place (Ort)
    • postalCode (string, required): Postal code
    • region (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"

View as Markdown · Interactive reference · OpenAPI