> For the complete documentation index, see [llms.txt](https://docs.borndigital.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.borndigital.ai/digital-agent/tools-reference/addresses-and-places.md).

# Addresses & places

Addresses, streets, cities, postcodes and distances.

Addresses, streets, cities, postcodes and distances. How to add a tool and use its result is described in [Tools & smart functions](https://docs.borndigital.ai/digital-agent/tools-reference.md).

| Tool                             | Technical name               | What it does                                                                                                                    | Languages          |
| -------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| Address                          | `address`                    | Extract the street name, street number, city, and postal code from a user's address input.                                      | cs, sk, hu, en     |
| Advanced address                 | `advanced_address`           | Extract street name, street number, city, and postal code from a user's address input, returning the first found address.       | cs, sk             |
| City extractor                   | `city`                       | Extract a city name from user input, handling declined forms and optional character indices.                                    | cs, sk, pl, de, hu |
| City extractor in nominative     | `city_extract_replace`       | Extract a city name in nominative case from user input, optionally returning its character indices.                             | cs, sk, hu, en     |
| Declined streets to cities       | `declined_streets_to_cities` | Extract the city name from street number from the last utterance.                                                               | sk, cs             |
| Distance between two cities      | `distance_city_to_city`      | Calculate distance between two cities.                                                                                          | cs, sk             |
| Postcode to city extractor       | `postcode_to_city`           | Extracts city names corresponding to postcodes found in a user's input.                                                         | sk, cs             |
| Postcodes from city              | `city_to_postcode`           | Extract zip codes for a given city name from user input.                                                                        | cs, sk, hu         |
| Postcodes from city and street   | `city_street_to_postcode`    | Extract zip codes based on a provided city and street combination.                                                              | cs, sk             |
| River names extractor            | `rivers`                     | Extract river names from the user utterance                                                                                     | cs, sk             |
| Street and number extractor      | `official_street_and_number` | Return the street name and number from the user’s utterance, with optional city context and number requirement.                 | cs, sk             |
| Street extractor                 | `street`                     | Extract the street name and number from the user’s utterance as a single string                                                 | cs, sk             |
| Street name and number extractor | `street_trie`                | Extract the street name and number from the user’s utterance as a single string, with options to require or separate the number | cs, sk, hu, pl, en |
| Zip code extractor               | `zipcode`                    | Extract the zip code number from the user’s utterance using strict matching                                                     | cs, sk, pl         |
| Zip code greedy extractor        | `zipcode_greedy`             | Extract the zip code number from the user’s utterance using a greedy matching approach                                          | cs, sk, pl, hu, en |

## Address

Technical name: `address`

Extract the street name, street number, city, and postal code from a user's address input.

* Languages: cs, sk, hu, en.

| Parameter                                               | Name                      | Required | Default | Description                                                                                |
| ------------------------------------------------------- | ------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------ |
| Require street number switch                            | `require_street_number`   | no       | `True`  | If true, the extractor requires the street to include a house number.                      |
| Recognize cities without streets as cities and streets. | `street_cities`           | no       | `True`  | Allow recognition of city names that overlap with street names.                            |
| Output street number separately                         | `street_number_separated` | no       | `False` | Return street number as a separate field instead of part of the street name.               |
| Custom input                                            | `custom_input`            | no       |         | Provide a custom text to extract the address from, instead of using the last user message. |

**Example input:** Masarykova 2, Brno 60200

**Example output:**

```
{'street': 'Masarykova 2', 'city': 'Brno', 'zipcode': '60200'}
```

## Advanced address

Technical name: `advanced_address`

Extract street name, street number, city, and postal code from a user's address input, returning the first found address.

* Languages: cs, sk.

| Parameter                                               | Name                      | Required | Default | Description                                                                                                                                                                                                                           |
| ------------------------------------------------------- | ------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Require street number switch                            | `require_street_number`   | no       | `True`  | If true, the extractor requires the street to include a house number.                                                                                                                                                                 |
| Recognize cities without streets as cities and streets. | `street_cities`           | no       | `True`  | Allow recognition of city names that overlap with street names.                                                                                                                                                                       |
| Ignore entities from provided list.                     | `blacklist`               | no       | `[]`    | Provide a list of entities to ignore during extraction.                                                                                                                                                                               |
| Match patterns with returned address entities.          | `valid_address_pattern`   | no       | `[]`    | Specify which combinations of address components must be present to consider an address valid. For example, \[\['street','city','zipcode']] ensures the extractor only accepts entries containing street name, city, and postal code. |
| Output street number separately                         | `street_number_separated` | no       | `False` | Return street number as a separate field instead of part of the street name.                                                                                                                                                          |
| Return anonymized utterance.                            | `anonymize_utterance`     | no       | `False` | Return an anonymized version of the original text alongside extracted addresses. For example, 'Deliver package to Masarykova 2, Brno 60200' becomes 'Deliver package to <-ADDRESS->'.                                                 |

**Example input:** Masarykova 2, Brno 60200

**Example output:**

```
[{'street': 'Masarykova 2', 'city': 'Brno', 'zipcode': '60200'}]
```

## City extractor

Technical name: `city`

Extract a city name from user input, handling declined forms and optional character indices.

* Languages: cs, sk, pl, de, hu.

| Parameter               | Name              | Required | Default | Description                                                                   |
| ----------------------- | ----------------- | -------- | ------- | ----------------------------------------------------------------------------- |
| Declined city detection | `declined_cities` | no       | `True`  | When on, detect declined city forms (e.g. 'Prahe' → 'Praha').                 |
| Custom input            | `custom_input`    | no       |         | Provide text to extract the city from instead of using the last user message. |

**Example input:** I live in Brno

**Example output:**

```
Brno
```

## City extractor in nominative

Technical name: `city_extract_replace`

Extract a city name in nominative case from user input, optionally returning its character indices.

* Languages: cs, sk, hu, en.

| Parameter                         | Name              | Required | Default | Description                                                                   |
| --------------------------------- | ----------------- | -------- | ------- | ----------------------------------------------------------------------------- |
| the best candidate indices switch | `get_indices`     | no       | `False` | When on, return the found city and its start/end character indices.           |
| Custom input                      | `custom_input`    | no       |         | Provide text to extract a city from instead of using the last user message.   |
| all indices switch                | `get_all_indices` | no       | `False` | When on, return all matched cities with their indices and the remaining text. |

**Example input:** I live in Bratislava

**Example output:**

```
Bratislava
```

## Declined streets to cities

Technical name: `declined_streets_to_cities`

Extract the city name from street number from the last utterance.

* Languages: sk, cs.

| Parameter    | Name           | Required | Default | Description                                                                                                         |
| ------------ | -------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| Custom input | `custom_input` | no       |         | custom input defined by the user from the flow. If set then it will be used as input instead of the last utterance. |

**Example input:** Masarykova 2

**Example output:**

```
[`Brno`]
```

## Distance between two cities

Technical name: `distance_city_to_city`

Calculate distance between two cities.

* Languages: cs, sk.

| Parameter        | Name     | Required | Default | Description       |
| ---------------- | -------- | -------- | ------- | ----------------- |
| Origin city      | `origin` | yes      |         | City of origin.   |
| Destination city | `dest`   | yes      |         | Destination city. |

**Example input:** origin: Brno, dest: Praha

**Example output:**

```
186.5
```

## Postcode to city extractor

Technical name: `postcode_to_city`

Extracts city names corresponding to postcodes found in a user's input.

* Languages: sk, cs.

| Parameter    | Name           | Required | Default | Description                                                    |
| ------------ | -------------- | -------- | ------- | -------------------------------------------------------------- |
| Custom input | `custom_input` | no       |         | Specify custom text containing postcodes to convert to cities. |

**Example input:** The postcode for my address is 10001.

**Example output:**

```
['New York']
```

## Postcodes from city

Technical name: `city_to_postcode`

Extract zip codes for a given city name from user input.

* Languages: cs, sk, hu.

| Parameter    | Name           | Required | Default | Description                                                                    |
| ------------ | -------------- | -------- | ------- | ------------------------------------------------------------------------------ |
| Custom input | `custom_input` | no       |         | Provide text containing the city name to use instead of the last user message. |

**Example input:** Trnava

**Example output:**

```
['917 01', '917 02', '917 05', '917 08']
```

## Postcodes from city and street

Technical name: `city_street_to_postcode`

Extract zip codes based on a provided city and street combination.

* Languages: cs, sk.

| Parameter    | Name           | Required | Default | Description                                                                                            |
| ------------ | -------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------ |
| Custom input | `custom_input` | no       |         | Provide text containing city and street to retrieve zip codes, instead of using the last user message. |

**Example input:** Brno+Hybešova

**Example output:**

```
['60200']
```

## River names extractor

Technical name: `rivers`

Extract river names from the user utterance

* Languages: cs, sk.

| Parameter    | Name           | Required | Default | Description                                |
| ------------ | -------------- | -------- | ------- | ------------------------------------------ |
| Custom input | `custom_input` | no       |         | Custom utterance text provided by the flow |

**Example input:** The rivers Bečva and Labe flow through the countryside

**Example output:**

```
['Bečva', 'Labe']
```

## Street and number extractor

Technical name: `official_street_and_number`

Return the street name and number from the user’s utterance, with optional city context and number requirement.

* Languages: cs, sk.

| Parameter             | Name             | Required | Default | Description                                                                           |
| --------------------- | ---------------- | -------- | ------- | ------------------------------------------------------------------------------------- |
| City                  | `city`           | no       |         | City to narrow street lookup (case-insensitive).                                      |
| Require street number | `require_number` | no       | `True`  | When on, only return a result when a street number is present.                        |
| Custom input          | `custom_input`   | no       |         | Override the user’s utterance with a custom string to extract street and number from. |

**Example input:** My address is Husova 5.

**Example output:**

```
Husova 5
```

## Street extractor

Technical name: `street`

Extract the street name and number from the user’s utterance as a single string

* Languages: cs, sk.

| Parameter    | Name           | Required | Default | Description                                |
| ------------ | -------------- | -------- | ------- | ------------------------------------------ |
| Custom input | `custom_input` | no       |         | Custom utterance text provided by the flow |

**Example input:** My address is Elm Street 742

**Example output:**

```
Elm Street 742
```

## Street name and number extractor

Technical name: `street_trie`

Extract the street name and number from the user’s utterance as a single string, with options to require or separate the number

* Languages: cs, sk, hu, pl, en.

| Parameter              | Name                      | Required | Default | Description                                                  |
| ---------------------- | ------------------------- | -------- | ------- | ------------------------------------------------------------ |
| Require number         | `require_number`          | no       | `True`  | Whether to require a street number for a successful match    |
| Separate street number | `street_number_separated` | no       | `False` | Whether to return the street number separately from the name |
| Custom input           | `custom_input`            | no       |         | Custom utterance text provided by the flow                   |
| Get all indices        | `get_all_indices`         | no       | `False` | Whether to return all matches with their indices             |

**Example input:** My address is Elm Street 742

**Example output:**

```
Elm Street 742
```

## Zip code extractor

Technical name: `zipcode`

Extract the zip code number from the user’s utterance using strict matching

* Languages: cs, sk, pl.

| Parameter    | Name           | Required | Default | Description                                                            |
| ------------ | -------------- | -------- | ------- | ---------------------------------------------------------------------- |
| Custom input | `custom_input` | no       |         | Custom text to extract a zip code from instead of the user’s utterance |

**Example input:** My postal code is 60200

**Example output:**

```
602 00
```

## Zip code greedy extractor

Technical name: `zipcode_greedy`

Extract the zip code number from the user’s utterance using a greedy matching approach

* Languages: cs, sk, pl, hu, en.

| Parameter       | Name              | Required | Default | Description                                                            |
| --------------- | ----------------- | -------- | ------- | ---------------------------------------------------------------------- |
| Custom input    | `custom_input`    | no       |         | Custom text to extract a zip code from instead of the user’s utterance |
| Get all indices | `get_all_indices` | no       | `False` | Whether to return all matching zip code indices                        |

**Example input:** My postal code is 60200

**Example output:**

```
60200
```
