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) coordinate – geographic coordinates in various formats If Type is not specified, the search is performed only in regional, poi (not coordinate). 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
CZ
- 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