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.

api.webp

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 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-v2/style.json?key=" + apiKey,
  center: [16.3, 49.2],
  zoom: 7,
});

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

map.addControl(gc);

autocomplete.gif

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

There are more advanced parameters of the API, giving developers greater control and power in their geocoding searches. These parameters include:

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

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.
  • continental_marine - continents and major ocean and sea divisions
  • country - countries
  • major_landform - large natural-related areas like mountain ranges, national parks, islands, forests
  • 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 - municipalities
  • municipal_district - districts within a municipalities
  • locality - localities
  • neighbourhood - neighborhoods
  • place - places, 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 codes
  • address - streets and addresses
  • road - roads
  • 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.