Geocoding API

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

Geocoding Features

• 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

Geocoding Control - autocomplete JavaScript component

You can easily create autocomplete search boxes using our prepared JavaScript component.

npm install --save @maptiler/geocoding-control maplibre-gl

import maplibregl from "maplibre-gl";
import { GeocodingControl } from "@maptiler/geocoding-control/maplibregl";
import "@maptiler/geocoding-control/dist/style.css";
import "maplibre-gl/dist/maplibre-gl.css";

const apiKey = "YOUR_MAPTILER_API_KEY_HERE";

const map = new maplibregl.Map({
  container: "map", // id of HTML container element
  style: "https://api.maptiler.com/maps/streets/style.json?key=" + apiKey,
  center: [16.3, 49.2],
  zoom: 7,
});

const gc = new GeocodingControl({ apiKey, maplibregl });

map.addControl(gc);

Read more about the JavaScript component at the Npmjs website, @maptiler/geocoding-control.

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 theautocompleteWaitMsparameter 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 India might return bothIndiaandIndianawith autocomplete enabled, but onlyIndiaif 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 returnWashington, DCfor a query ofwahsington, even though the query was misspelled.
• limit - controls the maximum number of results to return. The default is5and the max support is10.

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.
• autocomplete and fuzzyMatch: Setting parameters autocomplete and fuzzyMatch to false will 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 types parameter

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

Geocoding on-prem with MapTiler Server 

You can utilize the geocoding capabilities within your on-prem installation of MapTiler Server. This feature allows you to search for addresses and locations without an internet connection. Refer to the MapTiler Server API documentation for a comprehensive understanding of all the available options the geocoding API provides.