API für Postleitzahlen, Vorwahlen und Orte
Eine einfache JSON-Schnittstelle ohne Anmeldung und ohne Schlüssel. Abgefragt wird mit einer Postleitzahl, einer Vorwahl oder einem Ortsnamen.
Endpunkt
https://www.postleitzahl.net/at/api/json/{anfrage}
Anfragetypen
Der Typ wird automatisch erkannt. Eine rein numerische Eingabe mit der Stellenzahl des Landes gilt als Postleitzahl, eine andere Ziffernfolge als Vorwahl, alles Übrige als Ortsname. Mit ?type= lässt sich der Typ erzwingen.
| Beispiel | Typ | Bedeutung |
|---|---|---|
https://www.postleitzahl.net/at/api/json/1010 | postcode | Postleitzahl |
https://www.postleitzahl.net/at/api/json/0571 | prefix | Telefonvorwahl |
https://www.postleitzahl.net/at/api/json/Minden | place | Ortsname |
Parameter
| Parameter | Wirkung |
|---|---|
fields | kommagetrennte Liste der gewünschten Felder, z. B. ?fields=place,postalCode |
type | erzwingt postcode, prefix oder place |
lang | Sprache der übersetzbaren Felder, z. B. ?lang=en |
callback | JSONP-Funktionsname |
q | Anfrage als Parameter statt im Pfad: /api/json?q=Minden |
Sprache
Das Feld country wird übersetzt, wenn der Parameter lang gesetzt ist. Ortsnamen bleiben immer in der Landessprache, weil sie Eigennamen sind. Ohne lang entscheidet der Kopf Accept-Language des Aufrufers. Ein unbekannter Wert wird ignoriert.
de ar bg cs da el en es et fi fr ga hr hu it lt lv mt nl no pl pt ro sk sl sv uk zh
curl "https://www.postleitzahl.net/at/api/json/1010?lang=en"
{ "status": "success", "country": "Germany", "countryCode": "DE", "place": "Minden", "postalCode": "1010", "query": "1010", "type": "postcode" }
Antwortfelder
| Feld | Inhalt | Beispiel |
|---|---|---|
status | success oder fail | "success" |
query | die gestellte Anfrage | "1010" |
type | erkannter Anfragetyp: postcode, prefix oder place | "postcode" |
country | Land, über lang übersetzbar | "Österreich" |
countryCode | Ländercode nach ISO 3166-1 | "AT" |
place | Ortsname | "Minden" |
postalCode | Postleitzahl | "32423" |
message | nur bei status fail: der Grund | "not found" |
Nutzungsgrenze
Je IP-Adresse sind 10 Anfragen pro 5 Minuten zulässig. Jede Antwort nennt im Kopf X-Rl die verbleibenden Anfragen und X-Ttl die Sekunden bis zur Rückstellung. Wird die Grenze überschritten, antwortet die Schnittstelle mit dem Status 429, bis das Zeitfenster zurückgesetzt ist. Wer die Grenze in 3 aufeinanderfolgenden Zeitfenstern überschreitet, wird für 60 Minuten gesperrt.
{
"status": "fail",
"message": "rate limit exceeded, 10 requests per 5 minutes",
"query": "1010"
}
Fehlerantworten
| HTTP | message |
Ursache |
|---|---|---|
| 400 | missing query | keine Anfrage übergeben |
| 400 | query too long | mehr als 80 Zeichen |
| 404 | not found | kein Treffer |
| 429 | rate limit exceeded | Nutzungsgrenze erreicht, gilt bis zum Ende des Zeitfensters |
| 429 | banned for 60 minutes | Grenze mehrfach hintereinander überschritten |
Beispiele
curl https://www.postleitzahl.net/at/api/json/1010 curl "https://www.postleitzahl.net/at/api/json/Minden?fields=place,postalCode" curl "https://www.postleitzahl.net/at/api/json?q=0571&type=prefix"
Datenquellen
Gemeindeschlüssel, NUTS-Codes und Einwohnerzahlen stammen aus dem Gemeindeverzeichnis und der NUTS-Systematik von Eurostat. Die Zuordnung von Postleitzahlen zu Regionen folgt der amtlichen TERCET-Tabelle der Europäischen Kommission.