API für Postleitzahlen, Vorwahlen und Orte
Eine schlanke JSON-Schnittstelle, ohne Anmeldung und ohne Schlüssel. Fragen Sie mit einer Postleitzahl, einer Vorwahl oder einem Ortsnamen ab und erhalten Sie Ort, Land, Postleitzahlen und Vorwahlen zurück.
Endpunkt
https://www.postleitzahl.net/ch/api/json/{anfrage}
Anfragetypen
Sie müssen nicht angeben, was Sie abfragen. Die Schnittstelle erkennt es selbst und probiert die Deutungen der Reihe nach durch, bis eine trifft: Ziffernfolgen in der Länge einer Postleitzahl zuerst als Postleitzahl, kürzere oder längere Ziffernfolgen zuerst als Vorwahl, alles Übrige als Ortsname. Mit ?type= legen Sie den Typ selbst fest.
| Beispiel | Typ | Bedeutung |
|---|---|---|
https://www.postleitzahl.net/ch/api/json/3000 | postcode | Postleitzahl |
https://www.postleitzahl.net/ch/api/json/0571 | prefix | Telefonvorwahl |
https://www.postleitzahl.net/ch/api/json/Minden | place | Ortsname |
Parameter
| Parameter | Wirkung |
|---|---|
fields | kommagetrennte Liste der gewünschten Felder, z. B. ?fields=place,postcode |
type | legt den Anfragetyp fest: postcode, prefix oder place |
lang | Sprache der übersetzbaren Felder, z. B. ?lang=en |
callback | JSONP-Funktionsname |
q | die Anfrage als Parameter statt im Pfad: /api/json?q=Minden |
Sprache
Mit dem Parameter lang bestimmen Sie die Sprache der Antwort. Übersetzt wird der Ländername; Ortsnamen bleiben unverändert, da es sich um Eigennamen handelt. Fehlt der Parameter, richtet sich die Sprache nach dem Accept-Language-Header Ihrer Anfrage. Nicht unterstützte Werte werden 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/ch/api/json/3000?lang=en"
{ "status": "success", "country": "Germany", "countryCode": "DE", "place": "Minden", "postcode": "3000", "query": "3000", "type": "postcode" }
Antwortfelder
| Feld | Inhalt | Beispiel |
|---|---|---|
status | success oder fail | "success" |
query | die gestellte Anfrage | "3000" |
type | erkannter Anfragetyp: postcode, prefix oder place | "postcode" |
country | Land, über lang übersetzbar | "Schweiz" |
countryCode | Ländercode nach ISO 3166-1 | "CH" |
place | Ortsname, bei mehreren eine Liste | "Minden" |
postcode | Postleitzahl des Orts, bei mehreren eine Liste | ["32423","32425","32427","32429"] |
areacode | Telefonvorwahl des Orts, bei mehreren eine Liste | "0571" |
message | nur bei status fail: der Grund | "not found" |
Nutzungsgrenze
Pro IP-Adresse sind 10 Anfragen in 5 Minuten erlaubt. Jede Antwort führt im Header mit, wie viele Anfragen Ihnen noch bleiben (X-Rl) und in wie vielen Sekunden das Zeitfenster neu beginnt (X-Ttl). Ist das Kontingent erschöpft, antwortet die Schnittstelle bis zum Ende des Zeitfensters mit Status 429. Wer das Kontingent in 3 Zeitfenstern hintereinander ausreizt, wird für 60 Minuten gesperrt.
{
"status": "fail",
"message": "rate limit exceeded, 10 requests per 5 minutes",
"query": "3000"
}
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/ch/api/json/3000 curl "https://www.postleitzahl.net/ch/api/json/Minden?fields=place,postcode" curl "https://www.postleitzahl.net/ch/api/json?q=0571&type=prefix"
Datenquellen
Ortsdaten, Gemeindeschlüssel und Einwohnerzahlen stammen aus dem Gemeindeverzeichnis und der NUTS-Systematik von Eurostat. Welche Postleitzahl zu welcher Region gehört, richtet sich nach der amtlichen TERCET-Tabelle der Europäischen Kommission.