API for postal codes, area codes and places

The postleitzahl.net JSON API returns the matching place, the country and all linked postal codes and area codes for postal codes, area codes or place names.

Get an API key Integrate postal codes, places and area codes directly into your own application with an API key.
Sign up

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.

{
    "status": "success",
    "country": "Serbia",
    "countryCode": "RS",
    "place": "Beograd",
    "state": "Beograd",
    "postcode": [
        "11000",
        "11130",
        "11194",
        "11213",
        "11225",
        "11226",
        "11232",
        "11235",
        "11251",
        "11253",
        "11260",
        "11261",
        "11262",
        "11271",
        "11272",
        "11279",
        "11306",
        "11400",
        "11405",
        "11408",
        "11413",
        "11414",
        "11415",
        "11426",
        "11427",
        "11430",
        "11433",
        "11460",
        "11462",
        "11505",
        "11507",
        "11509",
        "11560",
        "11561",
        "11563",
        "11564",
        "11565",
        "11566"
    ],
    "areacode": [
        "011",
        "11"
    ],
    "query": "11000",
    "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/32423or/api?country=de&q=32423postcodepostal code
/api/de/0571or/api?country=de&q=0571prefixtelephone area code
/api/de/Mindenor/api?country=de&q=Mindenplaceplace name

Parameters

Parameter Effect
countryRequired: two-letter country code, e.g. de, nl or gb – either in the path (/api/de/32423) or as a parameter (country=de)
qSearch term as a parameter instead of in the path, e.g. /api?country=de&q=Minden
typeSets the request type: postcode, prefix or place
fieldsComma-separated list of the desired fields, e.g. ?fields=place,postcode
langlanguage of the translatable fields, e.g. ?lang=en
callbackName of the callback function for JSONP
tokenAPI 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
statusResult of the request: success or fail"success"
queryThe submitted request"11000"
typeDetected request type: postcode, prefix or place"postcode"
countryName of the country, translatable with lang"Germany"
countryCodeCountry code according to ISO 3166-1 Alpha-2"RS"
placePlace name; a list if there are several matches"Minden"
postcodePostal code of the place; a list if there are several["32423","32425","32427","32429"]
areacodeTelephone area code of the place; a list if there are several"0571"
messageOnly 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": "11000"
}

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
4011001missing api tokenThe request does not contain an API key.
4011002invalid api tokenThe API key is unknown or invalid.
4001003missing or unknown countryThe country code is missing or unknown.
4001004missing queryThe request does not contain a search term.
4001005query too longThe search term is longer than 80 characters.
4041006not foundNo entry was found for the search term.
4291007try-out limit exceededWhen trying it out on this page, at most 10 requests are possible in 5 minutes.
4291008rate limit exceededThe limit of 20 requests per minute has been reached. Requests are possible again from the next minute.
4291009try-out banned for 60 minutesThe try-out limit was exceeded 3 times in a row. Trying it out is then blocked for 60 minutes.
4001010bad requestThe request contains characters that are not allowed in the path. Send the search term URL-encoded or in the parameter q.
5031011service unavailableThe service is temporarily unavailable. Repeat the request after the number of seconds in the Retry-After header.
4041012no postcode system in this countryThe country has no postcode system. Place names and area codes are still found; the field postcode stays empty.

Examples

curl -H "X-Api-Token: plz_…" https://www.postleitzahl.net/api/rs/11000
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.

Postal codes worldwide

Albania AL Andorra AD Austria AT Belarus BY Belgium BE Bosnia and Herzegovina BA Bulgaria BG Croatia HR Cyprus CY Czechia CZ Denmark DK Estonia EE Finland FI France FR Germany DE Greece GR Hungary HU Iceland IS Ireland IE Italy IT Kosovo XK Latvia LV Liechtenstein LI Lithuania LT Luxembourg LU Malta MT Moldova MD Monaco MC Montenegro ME Netherlands NL North Macedonia MK Norway NO Poland PL Portugal PT Romania RO Russia RU San Marino SM Serbia RS Slovakia SK Slovenia SI Spain ES Sweden SE Switzerland CH Turkey TR Ukraine UA United Kingdom GB