Geocoding API

A set of functions focused on searching for addresses and locations, converting them into coordinates and vice versa. These functions are usually used for address validation (verification that a given address is valid) and for address suggestion (helping the client to enter a valid address).

Function description

Geocoding – Searches for entities (addresses) based on a textual query. Retrieves coordinates and additional information (e.g., surrounding regional structure)
Suggestion – Works similarly to geocoding but takes into account incomplete queries, so it can be used to suggest corresponding entities when the user types a location query.
Reverse geocoding – Returns regional entities based on coordinates (clicking on a map returns addresses at that point).

You can try out the functions in the Test Laboratory. For specific examples, see the Tutorials.

Technical documentation

https://api.mapy.cz/v1/docs/geocode/

The technical documentation provides an exact description of input and output parameters, default values, errors, and other details.

Input parameters (for Geocoding and Suggestion)

query	Search expression
lang	Preferred language of the names of the searched entities. (For example function returns for CZ: Praha 1 – Staré město, Česko, for EN: Prague 1 – Old Town, Czechia, etc.)
limit	Max. number of results
type	Required type of results (what is being searched) regional – searches in the entire regional structure (countries, cities, addresses,…) – regional.country – countries – regional.region – regions (in the Czech Republic, for example, region and county) – regional.municipality – municipalities – regional.municipality_part – parts of municipalities, districts – regional.street – streets – regional.address – addresses poi – points outside the regional structure (not yet subdivided) If Type is not specified, the search is performed in all types listed above. Note – for frequently used limitations on cities, villages, and districts, it is appropriate to use regional.municipality + regional.municipality_part (smaller villages are usually parts of municipalities)
locality	Limits the results to a specific locality. Results outside this locality are not returned. It is possible to enter the names of localities separated by commas (e.g., Prague 5, Lhota u Kolina), state codes (cz, gb, us, etc.), or bounding boxes ({minLon},{minLat},{maxLon}, {maxLat}) or their combinations. Locality names (except for state codes) are internally converted to bounding boxes. It is recommended to use bounding boxes to avoid ambiguity. If a textual locality is used, the corresponding bounding boxes (or “Not Found!” for unknown localities) are returned in the result, which can be used to replace textual localities next time. In the case of limitations to entire states, we recommend using state codes, which are more accurate than bounding boxes in this case.
preferBBox, preferNear, preferNearPrecision	Preference for results from a given area (bounding box or location/circle). Results outside the specified area are also returned; however, results from the desired area have priority.

Input Parameters for Reverse Geocoding

lon, lat	Coordinates where regional entities are searched
lang	Preferred language of returned entity names

Return Values

All three functions return the same data structure in the result. The structure contains an array of entities that match the query. For each entity, it returns:

name	Textual name (e.g. Týnská ulička 610/7)
label	Textual label (address, city, lookout tower, public transportation stop)
position	Longitude and latitude coordinates
type	Type of entity, see type in input parameters
location	Textual locality to which the entity belongs (e.g. Prague 1 – Old Town, Czech Republic). This is not just a regional structure transcription. Smart algorithms are used to shorten and omit duplicates within towns, districts, and parts of towns. Regions are only used when the city is not unique within the country.
regionalStructure	Complete breakdown of the regional structure to which the entity belongs. For each level, its textual name Name and its type Type are provided. Only for regional.country is the isoCode parameter present, which returns the two-letter ISO 3166-1 alpha-2 country code Types regional.region and regional.municipality_part can appear multiple times in the structure. However, they always have a fixed order within the country, from smallest to largest (e.g. in CZ, the first region is a district, the second is a region). But the depth and meaning are different in each country.
zip	ZIP code – only if we have data for the given country
locality	Information on the conversion of textual locality to a bounding box – see input parameter locality

Smart Search

The Geocoding and Suggest features search data using smart (and constantly evolving) algorithms. Here are some examples of what the search can handle:

Different input formats

Dlouhá 21, Praha 1
Dlouhá 737, Praha 1
Dlouhá 737/21, Praha
Dlouhá 21, 110 00
Dlouhá 21, Staré město

Differen torder

Dlouhá 21, Praha 1
Praha 1, Dlouhá 21
11000,Dlouhá 21
..

Different input languages

Václavské náměstí 1, Praha 1
Wenceslas Square 846/1
Wenzelsplatz 1, prager neustadt

Local names

Václavák 846/1

Typos, diacritics (only for suggest, machine learning model)

dloha 21 pracha 1
vaclafske namsti 1

Detailed data

No matter how smart the search is, it won’t find anything if it doesn’t search in a detailed database. Here’s what data our search works with:

Address points

The primary source is regularly imported RUIAN
The editorial team occasionally adds addresses “on demand” (if they are missing from RUIAN or if they are “unofficial” local designations)

Rest of the world

The foundation is made up of data from OpenStreetMap
We are gradually adding local registries in individual countries
- We have Slovakia, Austria, Poland, Switzerland, Belgium, Luxembourg, Slovenia, Estonia
- We are preparing the Netherlands, Finland, Denmark, Norway, Italy, etc.

We maintain regional data in the native language and search for translations into other languages and various alternative names.

ZIP codes

CZ, SK, Germany, Poland, Austria, Hungary, Italy, France, United Kingdom
We are preparing the rest of Western Europe