API for postal codes, area codes and places

Authentication

An API key is required for every request. Pass it either in the X-Api-Token header, as Authorization: Bearer <TOKEN> or as the query parameter token.

Endpoint

You can pass the country and the search term in the path or as parameters. Both notations return the same response in JSON format.

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

Try it

Here you can try out the API without an API key. An API key is required for requests from your own application.

Request

{
    "status": "fail",
    "message": "not found",
    "query": "10000",
    "type": "postcode"
}

Query types

The API detects the request type on its own: if the input matches the postal code format of the country, it first searches for a postal code. Other sequences of digits are treated as an area code, all other input as a place name. If the search returns no match, it checks the remaining types. Use the type parameter to set the type explicitly.

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

Parameters

Parameter	Effect
`country`	Required: two-letter country code, e.g. `de`, `nl` or `gb` – either in the path (`/api/de/32423`) or as a parameter (`country=de`)
`q`	Search term as a parameter instead of in the path, e.g. `/api?country=de&q=Minden`
`type`	Sets the request type: `postcode`, `prefix` or `place`
`fields`	Comma-separated list of the desired fields, e.g. `?fields=place,postcode`
`lang`	language of the translatable fields, e.g. `?lang=en`
`callback`	Name of the callback function for JSONP
`token`	API key as a query parameter, if you do not pass it in the header

Localization

Use the lang parameter to set the language of the response. The name of the country is translated; place names keep their original spelling. If lang is missing, the Accept-Language header of your request applies. Unknown language codes 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 -H "X-Api-Token: plz_…" "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`	Result of the request: success or fail	`"success"`
`query`	The submitted request	`"10000"`
`type`	Detected request type: postcode, prefix or place	`"postcode"`
`country`	Name of the country, translatable with lang	`"Germany"`
`countryCode`	Country code according to ISO 3166-1 Alpha-2	`"SK"`
`place`	Place name; a list if there are several matches	`"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: short description of the error	`"not found"`

Usage limit

Each API key allows 20 requests per minute. Every response contains the number of requests still available in the current minute in the X-Rl header and the seconds until the start of the next minute in the X-Ttl header.

{
  "status": "fail",
  "code": 1008,
  "message": "rate limit exceeded",
  "query": "10000"
}

Error responses

If a request fails, the response contains "status": "fail", a unique error code in the code field and a short message in the message field. In your application, evaluate the error code, not the text of the message.

HTTP	Code	message	Cause
401	`1001`	`missing api token`	The request does not contain an API key.
401	`1002`	`invalid api token`	The API key is unknown or invalid.
400	`1003`	`missing or unknown country`	The country code is missing or unknown.
400	`1004`	`missing query`	The request does not contain a search term.
400	`1005`	`query too long`	The search term is longer than 80 characters.
404	`1006`	`not found`	No entry was found for the search term.
429	`1007`	`try-out limit exceeded`	When trying it out on this page, at most 10 requests are possible in 5 minutes.
429	`1008`	`rate limit exceeded`	The limit of 20 requests per minute has been reached. Requests are possible again from the next minute.
429	`1009`	`try-out banned for 60 minutes`	The try-out limit was exceeded 3 times in a row. Trying it out is then blocked for 60 minutes.

Examples

curl -H "X-Api-Token: plz_…" https://www.postleitzahl.net/api/sk/10000
curl -H "X-Api-Token: plz_…" "https://www.postleitzahl.net/api/gb/SW1A%201AA"
curl -H "Authorization: Bearer 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

The data comes from the official directories of the respective countries and from open sources such as GeoNames, OpenStreetMap and Wikidata. In the EU member states, the NUTS classification of Eurostat and the TERCET table of the European Commission complement the assignment of postal codes to regions.