API for postal codes, area codes and places

The JSON API for postal codes, area codes and places. Send a postal code, an area code or a place name and get back the place, the country and all related postal codes and area codes.

Every request needs a developer token. Pass the token in the X-Api-Token header, as Authorization: Bearer … or as the token parameter.

Endpoint

Country and search term go either in the path or as URL parameters. Both forms return the same JSON response.

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

Try it

{
    "status": "success",
    "country": "Canada",
    "countryCode": "CA",
    "place": "Conception Bay South",
    "postcode": [
        "A1W",
        "A1X"
    ],
    "areacode": "709",
    "query": "A1W",
    "type": "postcode"
}

Query types

The API detects what you are looking for: input in the postal code format of the country is searched as a postal code first, other digits as an area code, everything else as a place name. If there is no match, the other types are checked. Use the type parameter to set the type yourself.

Example	Type	Meaning
`https://www.postleitzahl.net/api/de/32423`or`https://www.postleitzahl.net/api?country=de&q=32423`	postcode	postal code
`https://www.postleitzahl.net/api/de/0571`or`https://www.postleitzahl.net/api?country=de&q=0571`	prefix	telephone area code
`https://www.postleitzahl.net/api/de/Minden`or`https://www.postleitzahl.net/api?country=de&q=Minden`	place	place name

Parameters

Parameter	Effect
`country`	Required: the two-letter country code, e.g. `de`, `nl` or `gb` – in the path (`/api/de/32423`) or as a parameter (`country=de`)
`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 search term as a parameter instead of in the path: `/api?country=de&q=Minden`

Localization

Use the lang parameter to choose the language of the response. The country name is translated; place names stay in their original form. Without lang, the Accept-Language header of your request applies; unknown values are 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	`"CA"`
`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

With a developer token you can send 20 requests per minute. Every response shows in its headers how many requests are left in the current minute (X-Rl) and in how many seconds the next minute starts (X-Ttl).

{
  "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`	no token supplied
401	`1002`	`invalid api token`	token unknown or invalid
400	`1003`	`missing or unknown country`	The country code is missing or unknown.
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`	Try-out limit reached
429	`1008`	`rate limit exceeded, 20 requests per minute`	Request limit reached – available again from the next 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/ca/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.