European Postal Code API

Postleitzahlen pruefen, nachschlagen und Orte suchen. Aktuell werden ausschliesslich Daten aus Oesterreich (AT) importiert.

OpenAPI-Definition herunterladen · Alle Beispiele verwenden diesen Server.

Postleitzahl pruefen

Prueft, ob eine PLZ aktuell aktiv und adressierbar ist. Eine unbekannte PLZ oder noch nicht importierte Daten liefern false.

GET /api/v1/postal/validate?country=AT&postalCode=8700

{"valid":true}

Postleitzahl nachschlagen

Liefert den kanonischen Ort und, falls vorhanden, weitere Angaben zur PLZ. Fuer eine PLZ wird nur ein Ort gespeichert.

GET /api/v1/postal/lookup?country=AT&postalCode=8700

Nicht gefundene oder aktuell ungueltige PLZ liefern HTTP 404. PLZ immer als Text behandeln, damit fuehrende Nullen erhalten bleiben.

Orte suchen

Sucht nach einem woertlichen Ortsnamen-Praefix, unabhaengig von Gross- und Kleinschreibung. limit ist 1 bis 100 (Standard 50), offset 0 bis 10000 (Standard 0).

GET /api/v1/postal/search?country=AT&city=Leoben&limit=50&offset=0

Die Antwort ist ein JSON-Array mit country, postalCode und city; ohne Treffer ist es leer.

Betrieb und Grenzen

Der Import startet beim Start und danach taeglich um 03:00 Uhr in Europe/Vienna. Der erste Import kann beim Start der API noch laufen oder fehlschlagen; der technische Readiness-Check prueft nur die Datenbankverbindung. Den Importstatus im Server-Log pruefen.

Ungueltige Parameter liefern HTTP 400, Datenbankfehler HTTP 503; Fehlerantworten enthalten ein JSON-Feld error. Die API hat keine eigene Authentifizierung oder Zugriffsbeschraenkung. Fuer einen oeffentlichen Betrieb sind ein abgesichertes Gateway und TLS erforderlich. Vor Weiterverteilung die Lizenz und Nutzungsbedingungen der Quelldaten pruefen.