# OpenPLZ API

> Look up postal codes, places and streets in Germany, Austria, Switzerland and Liechtenstein: find the town for a postal code or the postal codes of a town, check that a street exists, search addresses, and list states, districts and municipalities with their official keys. Open data, no account or API key needed.

App · 9 actions. Web page: https://docs.lodol.com/docs/integrations/openplz

## Actions

### Find places by postal code or name

Find the towns, cities and villages for a postal code, or the postal codes of a place, in Germany, Austria, Switzerland or Liechtenstein. Each place comes with its municipality, district and state. Give a postal code, a name or both.

**Inputs**

- Country (`country`, text): The country to look in. Defaults to Germany. One of: `de` (Germany), `at` (Austria), `ch` (Switzerland), `li` (Liechtenstein). Default: `de`.
- Postal code (`postal_code`, text): A postal code, or its first digits to find every code that starts with them. D-10117 and 10 117 work too.
- Place (`name`, text): The town, city or village, such as München.
- Match (`match`, text): How names and postal codes are compared with what you type, ignoring upper and lower case. Defaults to Starts with. Pattern reads your text as a regular expression. One of: `starts_with` (Starts with), `exact`, `contains`, `pattern` (Pattern (regular expression)). Default: `starts_with`.
- Page (`page`, number): Which page of results to get, from 1. Defaults to the first. At least 1. Default: `1`.
- Page size (`page_size`, number): How many results a page holds, 1 to 50. Defaults to 50. From 1 to 50. Default: `50`.
- Get every page (`all_pages`, true/false): Get every result at once, up to 1,000, instead of one page. Page and Page size are then ignored. Default: `false`.

**Outputs**

- `count` (number): How many are in this result.
- `country` (text): The country's code, e.g. 'DE'.
- `country_name` (text): The country's name, e.g. 'Germany'.
- `has_more` (true/false): True when more match than this result holds.
- `next_page` (number): The page to ask for next with the same page size; empty on the last page.
- `page` (number): The page returned, from 1.
- `page_size` (number): How many a page holds.
- `places` (list): The matching places
- `summary` (text): One line saying what was found, e.g. 'Found 1 place in Germany'.
- `total` (number): How many match in all, across every page.
- `total_pages` (number): How many pages there are at this page size.

**Example output**

```json
{
  "count": 1,
  "country": "DE",
  "country_name": "Germany",
  "has_more": false,
  "next_page": null,
  "page": 1,
  "page_size": 50,
  "places": [
    {
      "district": null,
      "district_key": null,
      "label": "10117 Berlin",
      "municipality": "Berlin, Stadt",
      "municipality_key": "11000000",
      "municipality_type": "Kreisfreie Stadt",
      "name": "Berlin",
      "postal_code": "10117",
      "state": "Berlin",
      "state_key": "11",
      "state_short_name": null
    }
  ],
  "summary": "Found 1 place in Germany for postal code '10117' (exact).",
  "total": 1,
  "total_pages": 1
}
```

### Find streets

Find streets by name, postal code or place, or any mix, to check an address or find a street's postal code. Each street comes with its place, borough (Germany), municipality, district and state.

**Inputs**

- Country (`country`, text): The country to look in. Defaults to Germany. One of: `de` (Germany), `at` (Austria), `ch` (Switzerland), `li` (Liechtenstein). Default: `de`.
- Street (`street`, text): The street's name, such as Hauptstraße. In Germany, Straße, Strasse and Str. all match.
- Postal code (`postal_code`, text): A postal code, or its first digits to find every code that starts with them. D-10117 and 10 117 work too.
- Place (`locality`, text): The town, city or village the street is in, such as Köln.
- Match (`match`, text): How names and postal codes are compared with what you type, ignoring upper and lower case. Defaults to Starts with. Pattern reads your text as a regular expression. One of: `starts_with` (Starts with), `exact`, `contains`, `pattern` (Pattern (regular expression)). Default: `starts_with`.
- Page (`page`, number): Which page of results to get, from 1. Defaults to the first. At least 1. Default: `1`.
- Page size (`page_size`, number): How many results a page holds, 1 to 50. Defaults to 50. From 1 to 50. Default: `50`.
- Get every page (`all_pages`, true/false): Get every result at once, up to 1,000, instead of one page. Page and Page size are then ignored. Default: `false`.

**Outputs**

- `count` (number): How many are in this result.
- `country` (text): The country's code, e.g. 'DE'.
- `country_name` (text): The country's name, e.g. 'Germany'.
- `has_more` (true/false): True when more match than this result holds.
- `next_page` (number): The page to ask for next with the same page size; empty on the last page.
- `page` (number): The page returned, from 1.
- `page_size` (number): How many a page holds.
- `streets` (list): The matching streets
- `summary` (text): One line saying what was found, e.g. 'Found 1 place in Germany'.
- `total` (number): How many match in all, across every page.
- `total_pages` (number): How many pages there are at this page size.

**Example output**

```json
{
  "count": 1,
  "country": "DE",
  "country_name": "Germany",
  "has_more": false,
  "next_page": null,
  "page": 1,
  "page_size": 50,
  "streets": [
    {
      "borough": "Mitte",
      "district": null,
      "district_key": null,
      "label": "Pariser Platz, 10117 Berlin",
      "locality": "Berlin",
      "municipality": "Berlin, Stadt",
      "municipality_key": "11000000",
      "municipality_type": "Kreisfreie Stadt",
      "name": "Pariser Platz",
      "postal_code": "10117",
      "state": "Berlin",
      "state_key": "11",
      "state_short_name": null,
      "status": null,
      "street_key": null,
      "suburb": "Mitte"
    }
  ],
  "summary": "Found 1 street in Germany for street 'Pariser Platz' and place 'Berlin' (exact).",
  "total": 1,
  "total_pages": 1
}
```

### List districts

List the districts (Kreise or Bezirke) of a German federal state, an Austrian province or a Swiss canton, with their keys and types. In Germany, a government region's key lists only that region's districts.

**Inputs**

- Country (`country`, text): The country to look in. Defaults to Germany. One of: `de` (Germany), `at` (Austria), `ch` (Switzerland). Default: `de`.
- State, province or canton (`state`, text, required): Pick one, or type its name, abbreviation (such as BY or ZH) or key.
- Page (`page`, number): Which page of results to get, from 1. Defaults to the first. At least 1. Default: `1`.
- Page size (`page_size`, number): How many results a page holds, 1 to 50. Defaults to 50. From 1 to 50. Default: `50`.
- Get every page (`all_pages`, true/false): Get every result at once, up to 1,000, instead of one page. Page and Page size are then ignored. Default: `false`.

**Outputs**

- `count` (number): How many are in this result.
- `country` (text): The country's code, e.g. 'DE'.
- `country_name` (text): The country's name, e.g. 'Germany'.
- `districts` (list): The districts
- `has_more` (true/false): True when more match than this result holds.
- `next_page` (number): The page to ask for next with the same page size; empty on the last page.
- `page` (number): The page returned, from 1.
- `page_size` (number): How many a page holds.
- `summary` (text): One line saying what was found, e.g. 'Found 1 place in Germany'.
- `total` (number): How many match in all, across every page.
- `total_pages` (number): How many pages there are at this page size.

**Example output**

```json
{
  "count": 1,
  "country": "DE",
  "country_name": "Germany",
  "districts": [
    {
      "administrative_headquarters": "Starnberg",
      "government_region": "Oberbayern",
      "government_region_key": "091",
      "key": "09188",
      "name": "Starnberg",
      "short_name": null,
      "state": "Bayern",
      "state_key": "09",
      "state_short_name": null,
      "type": "Landkreis"
    }
  ],
  "has_more": true,
  "next_page": 2,
  "page": 1,
  "page_size": 1,
  "summary": "Found 96 districts in Bayern; showing 1 to 1.",
  "total": 96,
  "total_pages": 96
}
```

### List government regions

List the government regions (Regierungsbezirke) of a German federal state, with their keys and seats. Only some states have them, such as Bayern, Hessen and Nordrhein-Westfalen.

**Inputs**

- Federal state (`state`, text, required): Pick a German federal state, or type its name or key (such as Bayern or 09).
- Page (`page`, number): Which page of results to get, from 1. Defaults to the first. At least 1. Default: `1`.
- Page size (`page_size`, number): How many results a page holds, 1 to 50. Defaults to 50. From 1 to 50. Default: `50`.
- Get every page (`all_pages`, true/false): Get every result at once, up to 1,000, instead of one page. Page and Page size are then ignored. Default: `false`.

**Outputs**

- `count` (number): How many are in this result.
- `country` (text): The country's code, e.g. 'DE'.
- `country_name` (text): The country's name, e.g. 'Germany'.
- `has_more` (true/false): True when more match than this result holds.
- `next_page` (number): The page to ask for next with the same page size; empty on the last page.
- `page` (number): The page returned, from 1.
- `page_size` (number): How many a page holds.
- `regions` (list): The state's government regions
- `summary` (text): One line saying what was found, e.g. 'Found 1 place in Germany'.
- `total` (number): How many match in all, across every page.
- `total_pages` (number): How many pages there are at this page size.

**Example output**

```json
{
  "count": 1,
  "country": "DE",
  "country_name": "Germany",
  "has_more": true,
  "next_page": 2,
  "page": 1,
  "page_size": 1,
  "regions": [
    {
      "administrative_headquarters": "M\u00fcnchen",
      "key": "091",
      "name": "Oberbayern",
      "state": "Bayern",
      "state_key": "09"
    }
  ],
  "summary": "Bayern has 7 government regions; showing 1 to 1.",
  "total": 7,
  "total_pages": 7
}
```

### List municipal associations

List Germany's municipal associations (Gemeindeverbände, such as an Amt or a Verwaltungsgemeinschaft) in a federal state or district, with their keys and seats.

**Inputs**

- Federal state (`state`, text): Pick a German federal state, or type its name or key (such as Bayern or 09). Not needed when a district is given as a key.
- District (`district`, text): Leave empty for the whole state. Pick a district or government region, or give its key (such as 09171) or name.
- Page (`page`, number): Which page of results to get, from 1. Defaults to the first. At least 1. Default: `1`.
- Page size (`page_size`, number): How many results a page holds, 1 to 50. Defaults to 50. From 1 to 50. Default: `50`.
- Get every page (`all_pages`, true/false): Get every result at once, up to 1,000, instead of one page. Page and Page size are then ignored. Default: `false`.

**Outputs**

- `associations` (list): The municipal associations
- `count` (number): How many are in this result.
- `country` (text): The country's code, e.g. 'DE'.
- `country_name` (text): The country's name, e.g. 'Germany'.
- `has_more` (true/false): True when more match than this result holds.
- `next_page` (number): The page to ask for next with the same page size; empty on the last page.
- `page` (number): The page returned, from 1.
- `page_size` (number): How many a page holds.
- `summary` (text): One line saying what was found, e.g. 'Found 1 place in Germany'.
- `total` (number): How many match in all, across every page.
- `total_pages` (number): How many pages there are at this page size.

**Example output**

```json
{
  "associations": [
    {
      "administrative_headquarters": "Emmerting",
      "district": "Alt\u00f6tting",
      "district_key": "09171",
      "key": "091715101",
      "name": "Emmerting (VGem)",
      "state": "Bayern",
      "state_key": "09",
      "type": "Verwaltungsgemeinschaft"
    }
  ],
  "count": 1,
  "country": "DE",
  "country_name": "Germany",
  "has_more": true,
  "next_page": 2,
  "page": 1,
  "page_size": 1,
  "summary": "Found 5 municipal associations in Alt\u00f6tting; showing 1 to 1.",
  "total": 5,
  "total_pages": 5
}
```

### List municipalities

List the municipalities (Gemeinden or communes) of a state, province, canton or district, or all of Liechtenstein's, with their official keys, types and postal codes.

**Inputs**

- Country (`country`, text): The country to look in. Defaults to Germany. One of: `de` (Germany), `at` (Austria), `ch` (Switzerland), `li` (Liechtenstein). Default: `de`.
- State, province or canton (`state`, text): Pick one, or type its name, abbreviation (such as BY or ZH) or key. Not needed when a district is given as a key. Only when Country is Germany, Austria or Switzerland.
- District (`district`, text): Leave empty for the whole state, province or canton. Pick a district (in Germany, a government region too), or give its key or name. Only when Country is Germany, Austria or Switzerland.
- Page (`page`, number): Which page of results to get, from 1. Defaults to the first. At least 1. Default: `1`.
- Page size (`page_size`, number): How many results a page holds, 1 to 50. Defaults to 50. From 1 to 50. Default: `50`.
- Get every page (`all_pages`, true/false): Get every result at once, up to 1,000, instead of one page. Page and Page size are then ignored. Default: `false`.

**Outputs**

- `count` (number): How many are in this result.
- `country` (text): The country's code, e.g. 'DE'.
- `country_name` (text): The country's name, e.g. 'Germany'.
- `has_more` (true/false): True when more match than this result holds.
- `municipalities` (list): The municipalities
- `next_page` (number): The page to ask for next with the same page size; empty on the last page.
- `page` (number): The page returned, from 1.
- `page_size` (number): How many a page holds.
- `summary` (text): One line saying what was found, e.g. 'Found 1 place in Germany'.
- `total` (number): How many match in all, across every page.
- `total_pages` (number): How many pages there are at this page size.

**Example output**

```json
{
  "count": 1,
  "country": "DE",
  "country_name": "Germany",
  "has_more": true,
  "municipalities": [
    {
      "association": null,
      "association_key": null,
      "code": null,
      "district": "Starnberg",
      "district_key": "09188",
      "electoral_district": null,
      "government_region": "Oberbayern",
      "government_region_key": "091",
      "key": "09188113",
      "multiple_postal_codes": true,
      "name": "Berg",
      "postal_code": "82335",
      "short_name": null,
      "state": "Bayern",
      "state_key": "09",
      "state_short_name": null,
      "type": "Kreisangeh\u00f6rige Gemeinde"
    }
  ],
  "next_page": 2,
  "page": 1,
  "page_size": 1,
  "summary": "Found 15 municipalities in Starnberg; showing 1 to 1.",
  "total": 15,
  "total_pages": 15
}
```

### List places in an area

List every place and postal code in a state, province, canton or district, with the municipality each belongs to.

**Inputs**

- Country (`country`, text): The country to look in. Defaults to Germany. One of: `de` (Germany), `at` (Austria), `ch` (Switzerland). Default: `de`.
- State, province or canton (`state`, text): Pick one, or type its name, abbreviation (such as BY or ZH) or key. Not needed when a district is given as a key. Only when Country is Germany, Austria or Switzerland.
- District (`district`, text): Leave empty for the whole state, province or canton. Pick a district (in Germany, a government region too), or give its key or name. Only when Country is Germany, Austria or Switzerland.
- Page (`page`, number): Which page of results to get, from 1. Defaults to the first. At least 1. Default: `1`.
- Page size (`page_size`, number): How many results a page holds, 1 to 50. Defaults to 50. From 1 to 50. Default: `50`.
- Get every page (`all_pages`, true/false): Get every result at once, up to 1,000, instead of one page. Page and Page size are then ignored. Default: `false`.

**Outputs**

- `count` (number): How many are in this result.
- `country` (text): The country's code, e.g. 'DE'.
- `country_name` (text): The country's name, e.g. 'Germany'.
- `has_more` (true/false): True when more match than this result holds.
- `next_page` (number): The page to ask for next with the same page size; empty on the last page.
- `page` (number): The page returned, from 1.
- `page_size` (number): How many a page holds.
- `places` (list): The places
- `summary` (text): One line saying what was found, e.g. 'Found 1 place in Germany'.
- `total` (number): How many match in all, across every page.
- `total_pages` (number): How many pages there are at this page size.

**Example output**

```json
{
  "count": 1,
  "country": "DE",
  "country_name": "Germany",
  "has_more": true,
  "next_page": 2,
  "page": 1,
  "page_size": 1,
  "places": [
    {
      "district": "Starnberg",
      "district_key": "09188",
      "label": "82131 Gauting",
      "municipality": "Gauting",
      "municipality_key": "09188120",
      "municipality_type": "Kreisangeh\u00f6rige Gemeinde",
      "name": "Gauting",
      "postal_code": "82131",
      "state": "Bayern",
      "state_key": "09",
      "state_short_name": null
    }
  ],
  "summary": "Found 18 places with postal codes in Starnberg; showing 1 to 1.",
  "total": 18,
  "total_pages": 18
}
```

### List states, provinces or cantons

List Germany's 16 federal states, Austria's 9 federal provinces or Switzerland's 26 cantons, with their official keys (and each canton's abbreviation).

**Inputs**

- Country (`country`, text): The country to look in. Defaults to Germany. One of: `de` (Germany), `at` (Austria), `ch` (Switzerland). Default: `de`.

**Outputs**

- `count` (number): How many there are.
- `country` (text): The country's code, e.g. 'DE'.
- `country_name` (text): The country's name, e.g. 'Germany'.
- `states` (list): The states, provinces or cantons
- `summary` (text): One line saying what was found, e.g. 'Found 1 place in Germany'.

**Example output**

```json
{
  "count": 2,
  "country": "CH",
  "country_name": "Switzerland",
  "states": [
    {
      "key": "1",
      "name": "Z\u00fcrich",
      "seat_of_government": null,
      "short_name": "ZH"
    },
    {
      "key": "2",
      "name": "Bern / Berne",
      "seat_of_government": null,
      "short_name": "BE"
    }
  ],
  "summary": "Switzerland has 26 cantons."
}
```

### Search addresses

Search streets with free text: a street, postal code and place in any order, such as Pariser Platz Berlin. Accents and word order don't matter. Returns the matching streets with their postal codes and places.

**Inputs**

- Search for (`query`, text, required): Street, postal code and place in any order, such as Pariser Platz 10117 Berlin. Accents can be left out. Put words in quotes to find them side by side.
- Country (`country`, text): The country to look in. Defaults to Germany. One of: `de` (Germany), `at` (Austria), `ch` (Switzerland), `li` (Liechtenstein). Default: `de`.
- Page (`page`, number): Which page of results to get, from 1. Defaults to the first. At least 1. Default: `1`.
- Page size (`page_size`, number): How many results a page holds, 1 to 50. Defaults to 50. From 1 to 50. Default: `50`.
- Get every page (`all_pages`, true/false): Get every result at once, up to 1,000, instead of one page. Page and Page size are then ignored. Default: `false`.

**Outputs**

- `count` (number): How many are in this result.
- `country` (text): The country's code, e.g. 'DE'.
- `country_name` (text): The country's name, e.g. 'Germany'.
- `has_more` (true/false): True when more match than this result holds.
- `next_page` (number): The page to ask for next with the same page size; empty on the last page.
- `page` (number): The page returned, from 1.
- `page_size` (number): How many a page holds.
- `streets` (list): The matching streets
- `summary` (text): One line saying what was found, e.g. 'Found 1 place in Germany'.
- `total` (number): How many match in all, across every page.
- `total_pages` (number): How many pages there are at this page size.

**Example output**

```json
{
  "count": 1,
  "country": "DE",
  "country_name": "Germany",
  "has_more": false,
  "next_page": null,
  "page": 1,
  "page_size": 50,
  "streets": [
    {
      "borough": "Mitte",
      "district": null,
      "district_key": null,
      "label": "Pariser Platz, 10117 Berlin",
      "locality": "Berlin",
      "municipality": "Berlin, Stadt",
      "municipality_key": "11000000",
      "municipality_type": "Kreisfreie Stadt",
      "name": "Pariser Platz",
      "postal_code": "10117",
      "state": "Berlin",
      "state_key": "11",
      "state_short_name": null,
      "status": null,
      "street_key": null,
      "suburb": "Mitte"
    }
  ],
  "summary": "Found 1 street in Germany for 'Pariser Platz Berlin'.",
  "total": 1,
  "total_pages": 1
}
```
