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.