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.

Endpoint

https://www.postleitzahl.net/api/{country}/{query}
https://www.postleitzahl.net/api?country={country}&q={query}

Try it yourself

{
    "status": "success",
    "country": "Philippines",
    "countryCode": "PH",
    "place": "Dulag",
    "postcode": "6505",
    "areacode": "",
    "query": "6505",
    "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/32423https://www.postleitzahl.net/api?country=de&q=32423`	postcode	postal code
`https://www.postleitzahl.net/api/de/0571https://www.postleitzahl.net/api?country=de&q=0571`	prefix	telephone area code
`https://www.postleitzahl.net/api/de/Mindenhttps://www.postleitzahl.net/api?country=de&q=Minden`	place	place name

Parameters

Parameter	Effect
`country`
`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	`"PH"`
`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		message	Cause
401	`1001`	`missing api token`
401	`1002`	`invalid api token`
400	`1003`	`missing or unknown country`
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`
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/ph/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.