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 an API key. Pass the API key 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}
{
"status": "success",
"country": "Romania",
"countryCode": "RO",
"place": "Constanța",
"postcode": [
"900273",
"900001",
"900002",
"900003",
"900004",
"900005",
"900006",
"900007",
"900008",
"900012",
"900013",
"900014",
"900015",
"900016",
"900020",
"900021",
"900022",
"900023",
"900024",
"900025",
"900026",
"900027",
"900028",
"900029",
"900030",
"900031",
"900032",
"900033",
"900034",
"900035",
"900036",
"900037",
"900038",
"900039",
"900040",
"900041",
"900042",
"900043",
"900044",
"900045",
"900046",
"900047",
"900048",
"900049",
"900050",
"900051",
"900055",
"900056",
"900057",
"900058",
"900062",
"900063",
"900064",
"900068",
"900069",
"900070",
"900075",
"900076",
"900077",
"900082",
"900083",
"900088",
"900089",
"900090",
"900091",
"900095",
"900096",
"900097",
"900102",
"900103",
"900104",
"900105",
"900109",
"900110",
"900111",
"900116",
"900117",
"900118",
"900119",
"900122",
"900123",
"900124",
"900125",
"900130",
"900131",
"900132",
"900133",
"900137",
"900138",
"900139",
"900140",
"900144",
"900145",
"900146",
"900147",
"900152",
"900153",
"900154",
"900155",
"900160",
"900161",
"900162",
"900167",
"900168",
"900169",
"900170",
"900175",
"900176",
"900177",
"900178",
"900182",
"900183",
"900184",
"900189",
"900190",
"900191",
"900196",
"900197",
"900198",
"900199",
"900203",
"900204",
"900205",
"900206",
"900210",
"900211",
"900212",
"900217",
"900218",
"900219",
"900224",
"900225",
"900226",
"900227",
"900228",
"900229",
"900233",
"900234",
"900235",
"900236",
"900237",
"900238",
"900241",
"900242",
"900243",
"900247",
"900248",
"900249",
"900250",
"900251",
"900255",
"900256",
"900257",
"900258",
"900259",
"900263",
"900264",
"900265",
"900266",
"900270",
"900271",
"900272",
"900277",
"900278",
"900279",
"900280",
"900284",
"900285",
"900286",
"900287",
"900292",
"900293",
"900294",
"900295",
"900299",
"900300",
"900301",
"900302",
"900303",
"900307",
"900308",
"900309",
"900310",
"900311",
"900316",
"900317",
"900318",
"900319",
"900320",
"900326",
"900327",
"900328",
"900329",
"900330",
"900337",
"900338",
"900339",
"900340",
"900341",
"900345",
"900346",
"900347",
"900348",
"900349",
"900350",
"900354",
"900355",
"900356",
"900357",
"900362",
"900363",
"900364",
"900365",
"900366",
"900367",
"900371",
"900372",
"900373",
"900374",
"900375",
"900376",
"900377",
"900378",
"900379",
"900380",
"900382",
"900383",
"900384",
"900388",
"900389",
"900390",
"900394",
"900395",
"900396",
"900402",
"900403",
"900407",
"900408",
"900409",
"900412",
"900413",
"900414",
"900415",
"900419",
"900420",
"900421",
"900426",
"900427",
"900432",
"900433",
"900434",
"900438",
"900439",
"900440",
"900455",
"900456",
"900457",
"900462",
"900463",
"900464",
"900469",
"900470",
"900471",
"900472",
"900476",
"900477",
"900478",
"900482",
"900483",
"900487",
"900488",
"900489",
"900493",
"900494",
"900497",
"900498",
"900502",
"900503",
"900504",
"900507",
"900508",
"900511",
"900512",
"900513",
"900514",
"900517",
"900518",
"900519",
"900520",
"900524",
"900525",
"900526",
"900527",
"900532",
"900533",
"900534",
"900538",
"900539",
"900540",
"900544",
"900545",
"900546",
"900552",
"900553",
"900554",
"900559",
"900560",
"900561",
"900562",
"900565",
"900566",
"900567",
"900572",
"900573",
"900574",
"900575",
"900580",
"900581",
"900587",
"900588",
"900589",
"900590",
"900591",
"900592",
"900597",
"900598",
"900599",
"900600",
"900604",
"900605",
"900606",
"900607",
"900608",
"900612",
"900613",
"900614",
"900615",
"900619",
"900620",
"900621",
"900622",
"900627",
"900628",
"900629",
"900630",
"900634",
"900635",
"900636",
"900642",
"900643",
"900647",
"900648",
"900649",
"900652",
"900653",
"900654",
"900657",
"900658",
"900659",
"900663",
"900664",
"900665",
"900669",
"900670",
"900673",
"900674",
"900675",
"900676",
"900682",
"900683",
"900684",
"900685",
"900690",
"900691",
"900692",
"900693",
"900696",
"900697",
"900698",
"900699",
"900702",
"900703",
"900704",
"900705",
"900709",
"900710",
"900711",
"900716",
"900717",
"900720",
"900721",
"900725",
"900726",
"900727",
"900728",
"900732",
"900733",
"900734",
"900735",
"900742",
"900743",
"900744",
"900745",
"900746"
],
"areacode": [
"0241",
"0341",
"241"
],
"query": "900273",
"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/32423orhttps://www.postleitzahl.net/api?country=de&q=32423 | postcode | postal code |
https://www.postleitzahl.net/api/de/0571orhttps://www.postleitzahl.net/api?country=de&q=0571 | prefix | telephone area code |
https://www.postleitzahl.net/api/de/Mindenorhttps://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 | "RO" |
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 an API key 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",
"query": "10000"
}
Error responses
| HTTP | Code | message | Cause |
|---|---|---|---|
| 401 | 1001 | missing api token | no API key sent |
| 401 | 1002 | invalid api token | API key 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 in 5 minutes reached while trying it out on this page (without API key) |
| 429 | 1008 | rate limit exceeded | 20 requests per minute reached with the API key – available again from the next minute |
| 429 | 1009 | try-out banned for 60 minutes | Try-out limit exceeded 3 times in a row – blocked for 60 minutes |
Examples
curl -H "X-Api-Token: plz_…" https://www.postleitzahl.net/api/ro/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.
