# Ort aus PLZ, PLZ aus Ort (https://developer.bimetrics.de/reference/contacts/lookup-postal-code)

`GET https://app.bimetrics.de/api/address/postal`

operationId: `lookupPostalCode` · Berechtigung (Scope): `contacts:read` · Bereich: Kontakte

Liefert für Deutschland und Österreich die Orte einer Postleitzahl (`cities`) oder die Postleitzahlen eines Orts (`postalCodes`), wie die Vorschläge im Kontakt der App; mit beiden Parametern kommt beides. Kennt das Land die PLZ nicht, das andere aber schon, nennt `elsewhere` dieses Land, etwa Österreich für 4020. Die Listen sind nicht vollständig, Großkunden- und Postfach-PLZ fehlen oft. Eine unbekannte PLZ ist deshalb kein Fehler, die Listen bleiben dann leer. Für andere Länder kommt `supported: false`. Ohne `postalCode` und `city` antwortet die Route mit `400`. Quellen: für Deutschland OpenStreetMap (ODbL 1.0), für Österreich die RTR-GmbH. Zeigst du die Vorschläge an, nenne `attribution`, bei `osm` mit Link auf https://www.openstreetmap.org/copyright.

Benötigt einen Schlüssel mit der Berechtigung `contacts:read` oder `read`.

### Authentifizierung

`Authorization: Bearer bm_…` (alternativ `X-API-KEY: bm_…`, nie beide zugleich).

### Parameter

| Name | Ort | Pflicht | Typ | Beschreibung |
| --- | --- | --- | --- | --- |
| `country` | query | nein | string | Land als ISO-Code, `DE` oder `AT`; ein Name wie „Österreich“ geht auch. |
| `postalCode` | query | nein | string | Postleitzahl; Leerzeichen zählen nicht. |
| `city` | query | nein | string | Ort, ohne Rücksicht auf Groß- und Kleinschreibung. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/address/postal" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY"
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: PostalLookup |
| 400 | Ungültige Anfrage, z. B. ein Parameter mit ungültigem Wert wie eine ID, die keine UUID ist; korrigieren statt wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |
| 401 | Kein gültiger Schlüssel: fehlt (`Unauthorized`), ist unbekannt, abgelaufen oder widerrufen oder wurde nicht in genau einem Header gesendet (`InvalidAPIKey`). Schlüssel prüfen, nicht wiederholen. Auch eine ID, die zu einer anderen Firma gehört, ergibt `401 Unauthorized`. | `application/json`: Error |
| 403 | Dem Schlüssel fehlt die Berechtigung für diese Route (`APIKeyPermissionDenied`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder des Abos (`APIUnavailable`). | `application/json`: Error |
| 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `application/json`: Error |
| 429 | Zu viele Anfragen; nach `Retry-After` Sekunden erneut senden. Mehr unter [Fehler](https://developer.bimetrics.de/errors). (Header: Retry-After) | `application/json`: Error |
| 500 | Serverfehler; die Anfrage später wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |

#### Felder der Antwort 200 (`PostalLookup`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `attribution` | string | Namensnennung, die zu den Vorschlägen gehört, etwa „© OpenStreetMap-Mitwirkende“. |
| `cities` | Array<string> | Orte der Postleitzahl, der häufigste zuerst; leer, wenn die Liste sie nicht kennt. Nur mit `postalCode`. |
| `city` | string | Der angefragte Ort; nur mit `city`. |
| `country` | string | Land der Anfrage als ISO-Code. |
| `elsewhere` | PostalElsewhere | Nur wenn das Land die Postleitzahl nicht kennt, das andere (DE oder AT) aber schon. |
| `postalCode` | string | Die angefragte Postleitzahl ohne Leerzeichen; nur mit `postalCode`. |
| `postalCodes` | Array<string> | Postleitzahlen des Orts, aufsteigend, höchstens 20; leer, wenn die Liste den Ort nicht kennt. Nur mit `city`. |
| `source` | string | Quelle der Liste: `osm` (OpenStreetMap, Deutschland) oder `rtr` (RTR-GmbH, Österreich); fehlt bei anderen Ländern. |
| `supported` | boolean | `true` für DE und AT, sonst `false` mit leeren Listen. |

Verschachtelte Schemas stehen vollständig in der OpenAPI-Beschreibung: https://app.bimetrics.de/api/openapi.json