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.

Endpoint

https://www.postleitzahl.net/api/json/{query}

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/json/32423	postcode	postal code
https://www.postleitzahl.net/api/json/0571	prefix	telephone area code
https://www.postleitzahl.net/api/json/Minden	place	place name

Parameters

Parameter	Effect
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 bg cs da el en es et fi fr ga hr hu it lt lv mt nl no pl pt ro ru sk sl sv tr uk zh

curl "https://www.postleitzahl.net/api/json/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	"32423"
type	detected query type: postcode, prefix or place	"postcode"
country	country, translatable via lang	"Germany"
countryCode	country code per ISO 3166-1	"DE"
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 10 requests per 5 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 3 consecutive windows results in a 60 minute ban.

{
  "status": "fail",
  "message": "rate limit exceeded, 10 requests per 5 minutes",
  "query": "32423"
}

Error responses

HTTP	message	Cause
400	missing query	no query supplied
400	query too long	more than 80 characters
404	not found	no match
429	rate limit exceeded	usage limit reached, applies until the end of the window
429	banned for 60 minutes	limit exceeded repeatedly

Examples

curl https://www.postleitzahl.net/api/json/32423
curl "https://www.postleitzahl.net/api/json/Minden?fields=place,postcode"
curl "https://www.postleitzahl.net/api/json?q=0571&type=prefix"

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.