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

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

Input parameters (for Geocoding and Suggestion)

querySearch expression
langPreferred 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.)
limitMax. number of results
typeRequired type of results (what is being searched)

regional – searches in the entire regional structure (countries, cities, addresses,…)
– – 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)
localityLimits 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, preferNearPrecisionPreference 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, latCoordinates where regional entities are searched
langPreferred 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:

nameTextual name (e.g. Týnská ulička 610/7)
labelTextual label (address, city, lookout tower, public transportation stop)
positionLongitude and latitude coordinates
typeType of entity, see type in input parameters
locationTextual 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.
regionalStructureComplete 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 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.
zipZIP code – only if we have data for the given country
localityInformation 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