API for postal codes, area codes and places
A lean JSON interface — no registration, no API key, no rate limit. Send a postal code, an area code or a place name and receive the place, its country and all matching postal codes and area codes as structured JSON.
Entwickler-Token
Für jede Anfrage brauchen Sie einen Entwickler-Token. Sie erhalten ihn im Developer-Bereich Ihres Kontos für €9.90 pro Jahr inkl. MwSt. Übergeben Sie den Token im Header X-Api-Token, als Authorization: Bearer … oder als Parameter token.
Endpoint
Land und Anfrage stehen entweder im Pfad oder als Parameter in der URL. Beide Schreibweisen liefern dieselbe Antwort, immer im JSON-Format.
https://www.postleitzahl.net/api/{country}/{query}
https://www.postleitzahl.net/api?country={country}&q={query}
{
"status": "success",
"country": "Brazil",
"countryCode": "BR",
"place": "Mossoró",
"postcode": [
"59628",
"59600",
"59600-000",
"59603",
"59604",
"59605",
"59607",
"59608",
"59609",
"59610",
"59611",
"59612",
"59613",
"59614",
"59615",
"59616",
"59617",
"59618",
"59619",
"59620",
"59621",
"59622",
"59623",
"59625",
"59626",
"59627",
"59630",
"59631",
"59632",
"59633",
"59634",
"59635",
"59640",
"59642",
"59643",
"59645",
"59646",
"59649"
],
"areacode": "84",
"query": "59628",
"type": "postcode"
}
Query types
The type is detected automatically. A numeric input with the country's postal code length is treated as a postal code, any other digit sequence as an area code, everything else as a place name. Use ?type= to force the type.
| Example | Type | Meaning |
|---|---|---|
https://www.postleitzahl.net/api/de/32423oderhttps://www.postleitzahl.net/api?country=de&q=32423 | postcode | postal code |
https://www.postleitzahl.net/api/de/0571oderhttps://www.postleitzahl.net/api?country=de&q=0571 | prefix | telephone area code |
https://www.postleitzahl.net/api/de/Mindenoderhttps://www.postleitzahl.net/api?country=de&q=Minden | place | place name |
Parameters
| Parameter | Effect |
|---|---|
country | Pflichtangabe: der zweistellige Ländercode, z. B. de, nl oder gb – im Pfad (/api/gb/SW1A 1AA) oder als Parameter (country=gb) |
fields | comma separated list of the desired fields, e.g. ?fields=place,postcode |
type | sets the query type: postcode, prefix or place |
lang | language of the translatable fields, e.g. ?lang=en |
callback | JSONP function name |
q | the query as a parameter instead of in the path: /api/json?q=Minden |
Localization
The country field is translated when the lang parameter is set. Place names always stay in the national language because they are proper nouns. Without lang the caller's Accept-Language header decides. An unknown value is ignored.
de ar be bg bs ca cs da el en es et fa fi fr ga he hi hr hu hy id is it ja ka km ko lo lt lv mk mn ms mt ne nl no pl pt ro ru sk sl sq sr sv th tr uk vi zh
curl "https://www.postleitzahl.net/api/de/32423?lang=en"
{ "status": "success", "country": "Germany", "countryCode": "DE", "place": "Minden", "postcode": "32423", "query": "32423", "type": "postcode" }
Response fields
| Field | Content | Example |
|---|---|---|
status | success or fail | "success" |
query | the submitted query | "10000" |
type | detected query type: postcode, prefix or place | "postcode" |
country | country, translatable via lang | "Germany" |
countryCode | country code per ISO 3166-1 | "BR" |
place | place name, a list if there are several | "Minden" |
postcode | postal code of the place, a list if there are several | ["32423","32425","32427","32429"] |
areacode | telephone area code of the place, a list if there are several | "0571" |
message | only with status fail: reason | "not found" |
Usage limit
Each IP address may send 20 requests per 10 minutes. Every response reports the remaining requests in the X-Rl header and the seconds until the reset in X-Ttl. Once the limit is exceeded the interface answers with status 429 until the rate limit window is reset. Going over the limit in 5 consecutive windows results in a 3 minute ban.
{
"status": "fail",
"code": 1008,
"message": "rate limit exceeded, 20 requests per minute",
"query": "10000"
}
Error responses
| HTTP | Code | message | Cause |
|---|---|---|---|
| 401 | 1001 | missing api token | kein Token übergeben |
| 401 | 1002 | invalid api token | Token unbekannt oder ungültig |
| 400 | 1003 | missing or unknown country | Der Ländercode fehlt oder ist unbekannt. |
| 400 | 1004 | missing query | no query supplied |
| 400 | 1005 | query too long | more than 80 characters |
| 404 | 1006 | not found | no match |
| 429 | 1007 | try-out limit exceeded, 10 requests per 5 minutes without api token | usage limit reached, applies until the end of the window |
| 429 | 1008 | rate limit exceeded, 20 requests per minute | Grenze für Anfragen mit Token erreicht, gilt nur bis zum Ende der Minute |
| 429 | 1009 | try-out banned for 60 minutes, limit exceeded repeatedly | limit exceeded repeatedly |
Examples
curl -H "X-Api-Token: plz_…" https://www.postleitzahl.net/api/br/10000 curl -H "X-Api-Token: plz_…" "https://www.postleitzahl.net/api/gb/SW1A%201AA" curl -H "X-Api-Token: plz_…" "https://www.postleitzahl.net/api/de/Minden?fields=place,postcode" curl "https://www.postleitzahl.net/api?country=de&q=0571&type=prefix&token=plz_…"
Data sources
Municipality keys, NUTS codes and population figures come from the municipality register and the NUTS classification of Eurostat. The assignment of postal codes to regions follows the official TERCET table of the European Commission.
