Geocoding control (place search box)

The geocoding control implements a complete place search in your map or other frontend application. This page explains how to implement it with MapTiler SDK JS.

Get started

For the most basic integration, see the code example Add place search to map.

If you’re using a JS framework like React or Svelte, get tailored instructions in these tutorials:

You can also go to GitHub or npm for integration details.

To customize the geocoding control behavior for your needs, see these examples:

The search control has many more powerful config options, including autocomplete and typing predictions or highlighting search results on the map. Check out the geocoding control API reference to see all options.

Advanced topics

The geocoding control can be used as an ES Module (ESM) or UMD (Universal Module Definition).

UMD global variables

When importing scripts from CDN using <script> tags, the library creates global variables according to this table:

Script filename UMD global variable name Exports
maptilersdk.umd.js maptilersdkMaptilerGeocoder class GeocodingControl, function createMapLibreGlMapController
leaflet.umd.js leafletMaptilerGeocoder class GeocodingControl, function createLeafletMapController
maplibregl.umd.js maplibreglMaptilerGeocoder class GeocodingControl, function createMapLibreGlMapController
openlayers.umd.js openlayersMaptilerGeocoder class GeocodingControl, function createOpenLayersMapController
react.umd.js reactMaptilerGeocoder class GeocodingControl
vanilla.umd.js maptilerGeocoder class GeocodingControl
leaflet-controller.umd.js leafletMaptilerGeocodingController function createLeafletMapController
maplibregl-controller.umd.js maplibreglMaptilerGeocodingController function createMapLibreGlMapController
openlayers-controller.umd.js openlayersMaptilerGeocodingController function createOpenLayersMapController

The variable is an object with properties representing library-exported variables, for example maplibreglMaptilerGeocoder.GeocodingControl.

Alternatively you can use different CDN, for example https://www.unpkg.com/@maptiler/geocoding-control@${version}/${Script filename}. Replace ${version} with the desired library version and ${Script filename} with the script filename from the table above.

POI icons and bundlers

POI icons are served from CDN by default. If you need to serve them from a different location when using a web application bundler (Webpack, Vite), you’ll need additional configuration.

Icons are bundled in the library at node_modules/@maptiler/geocoding-control/icons. You can either:

  1. Configure your bundler to handle the icons directory
  2. Use the iconsBaseUrl configuration option to specify the icon location
  3. Copy the icons to your public directory

Related examples

Geocoding: Show place search results

Geocoding API

Tutorial

This tutorial shows how to search places using the MapTiler Geocoding API.
How to search places by coordinates (reverse geocoding)

Reverse geocoding

Tutorial

This tutorial shows how to search places by coordinates (reverse geocoding).
Geocoding: Add place search to map

Geocoding control

Tutorial

This tutorial shows how to search for places using the geocoding control.
Customize API request from geocoding control

Customize API request (geocoding control)

Example

Use the adjustUrl option in the geocoding control constructor to modify the geocoding URL before the fetch. This capability enables complete control over the search control's functionality.
Geocoding limit results by a drawn area

Geocoding limit results by a drawn area

Example

Limit geocode control search results to the bounding box of the drawn area. Draw a polygon on the map to filter the search results to the polygon bounding box.
Geocoding limit results by area (bounding box)

Geocoding limit results by area

Example

Limit the search results of the geocoding control to the specific area (bounding box).
Geocoding search for POIs near the user's location

Geocoding search for POIs near the user's location

Example

Geocoding control search results filter by type and given higher priority for the results near the user's location.
Geocoding search results closer to specific point

Geocoding search results by proximity to a specific point

Example

Geocoding control search results closer to the specific geographical point, results near the provided point are ranked higher.
Geocoding search results to specified country(ies)

Geocoding search results to specified country(ies)

Example

Geocoding control limit search results to specified country(ies).
How to specify the geocoding control language(s) response text and prioritization

Geocoding language

Example

Specify the geocoding control language(s) that are used for the response text and weighting of the query results.
Reverse geocoding uses the user’s location to search for places

Reverse geocoding uses the user’s location

Example

How to search for places by coordinates (reverse geocoding) using the user's location. Reverse geocoding transforms coordinates into place names.
Search features by coordinates using the geocoding control

Geocoding control (reverse geocoding)

Example

Support coordinate-based searches (reverse geocoding) using the geocoding control.