Geocoding is the process of transforming place names into geographical coordinates. Reverse geocoding works in the opposite direction, transforming coordinates into place names. This article describes how both processes work inside of the MapTiler ecosystem.
Our Geocoding Service is part of MapTiler Cloud and is available from the MapTiler API endpoint. The service requires a MapTiler Cloud API key, which can be obtained for free from the MapTiler Cloud account pages. Check out the pricing page for more information about what else MapTiler Cloud offers.
For more detailed documentation on how to use geocoding, have a look at these resources:
- Geocoding API reference documentation
- MapTiler Cloud administration page for Key management
- MapTiler Geocoding control package at npmjs.com
- Fast response times - for interactive search fields in forms
- Language choices - for localized outputs
- Regional searching - to avoid results out of the area of interest
- Proximity searching - to focus on your area of interest
- Fuzzy matching - to get results even when there are typos
- Reverse geocoding - to get coordinates from full addresses up to states
When using the autocomplete component, a new request is made every time the user input changes. The frequency of these requests can be tuned with the
autocompleteWaitMsparameter when initializing the component (see the documentation).
Geocoding API advanced parameters
country- limits searches to a specific country. One or more countries specified as comma-separated values ISO 3166 alpha 2 country codes.
types- filter results to include only a subset (one or more) of the available feature types. See the type hierarchy below for allowed values. Multiple options can be comma-separated.
autocomplete- (already mentioned) specify whether to return autocomplete results (
true) or not (
false). When autocomplete is enabled, results will be included that start with the requested string, rather than just responses that match it exactly. For example, a query
Indiamight return both
Indianawith autocomplete enabled, but only
Indiaif it’s disabled. The default is to combine exact results autocomplete.
When autocomplete is enabled, each user keystroke counts as one request to the Geocoding API. For example, a search for "coff" would be reflected as four separate Geocoding API requests. To reduce the total requests sent, you can configure your application to only call the Geocoding API after a specific number of characters are typed.
fuzzyMatch- specify whether the Geocoding API should attempt approximate, as well as exact matching when performing searches (
true, default), or whether it should opt out of this behavior and only attempt exact matching (
false). For example, the default setting might return
Washington, DCfor a query of
wahsington, even though the query was misspelled.
limit- controls the maximum number of results to return. The default is
5and the max support is
Parameters in practical usage
country: You may want to search for places exclusively in Norway. This way you can effectively exclude Oslo - the capital of Norway, from other Oslo - located in Minnesota, USA.
fuzzyMatch: Setting parameters
falsewill ensure that the result will contain only results exactly matching your query without trying to treat your input as possible with a typo or as a start of a complete place name. For example, if your search query is "koln" and the language is set to German, then the result will include Köln but won't include places like Kolin (in Czechia) or Kola (in Russia).
types- Because every country in the world has a different way of hierarchical division, it is not possible to design a universal one that fits every country. Maptiler Geocoding tries to approach this by defining an approximate global hierarchy where it maps every country by best effort. Not every country has administrative areas present at every level.
List of possible values of the
NOTE: this list may be slightly outdated from time to time, as we update this documentation article. For complete up-to-date list, please visit official API documentation page.
country- the country
region- the first level of division within the country
subregion- the second level of division within the country
county- the third level of division within the country
joint_municipality- a group of municipalities
joint_submunicipality- a group of sub municipalities
municipality- a municipality
municipal_district- a district within a municipality
locality- a locality
neighbourhood- a neighborhood
place- a place, such as a municipality, hamlet, isolated dwelling, square, etc. Also serves as a fallback for places that cannot be categorized into higher levels of hierarchy.
postal_code- postal code
address- street and address
poi- points of interest