Address Search with MapTiler SDK

MapTiler SDK

Search for a place name and display the result on the map using the MapTiler Geocoding API and SDK.

progress_activityLoading map...

maptilersdk.config.apiKey = 'YOUR_MAPTILER_KEY';
const map = new maptilersdk.Map({
  container: 'map',
  style: maptilersdk.MapStyle.STREETS,
  center: [2.3522, 48.8566],
  zoom: 5
});
let marker, timeout;
const input = document.getElementById('search-box');
const results = document.getElementById('results');
input.addEventListener('input', () => {
  clearTimeout(timeout);
  const q = input.value.trim();
  if (q.length < 3) { results.style.display = 'none'; return; }
  timeout = setTimeout(async () => {
    const res = await fetch('https://api.maptiler.com/geocoding/' + encodeURIComponent(q) + '.json?key=YOUR_MAPTILER_KEY&limit=5');
    const data = await res.json();
    results.innerHTML = '';
    results.style.display = data.features.length ? 'block' : 'none';
    data.features.forEach(f => {
      const div = document.createElement('div');
      div.textContent = f.place_name;
      div.onclick = () => {
        const [lng, lat] = f.center;
        if (marker) marker.remove();
        marker = new maptilersdk.Marker({ color: '#9C27B0' }).setLngLat([lng, lat]).addTo(map);
        new maptilersdk.Popup().setLngLat([lng, lat]).setHTML('<b>' + f.place_name + '</b>').addTo(map);
        map.flyTo({ center: [lng, lat], zoom: 14 });
        results.style.display = 'none';
        input.value = f.place_name;
      };
      results.appendChild(div);
    });
  }, 300);
});

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" href="https://cdn.maptiler.com/maptiler-sdk-js/v4.1.0/maptiler-sdk.css" />
<script src="https://cdn.maptiler.com/maptiler-sdk-js/v4.1.0/maptiler-sdk.umd.min.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { width: 100%; height: 100vh; }
#search-box { position: absolute; top: 10px; left: 10px; z-index: 1; padding: 8px 12px; font-size: 12px; font-family: monospace; background: #141414; color: #e0e0e0; border: 2px solid #2a2a2a; width: 280px; }
#results { position: absolute; top: 42px; left: 10px; z-index: 1; background: #141414; border: 2px solid #2a2a2a; border-top: none; width: 280px; max-height: 200px; overflow-y: auto; display: none; }
#results div { padding: 8px 12px; cursor: pointer; font-size: 11px; font-family: monospace; color: #c0c0c0; border-bottom: 1px solid #1e1e1e; }
#results div:hover { background: #1a1a1a; color: #e0e0e0; }

</style>
</head>
<body>
<div id="map"></div>
<input id="search-box" type="text" placeholder="Search address..." />
<div id="results"></div>

<script>
maptilersdk.config.apiKey = 'YOUR_MAPTILER_KEY';
const map = new maptilersdk.Map({
  container: 'map',
  style: maptilersdk.MapStyle.STREETS,
  center: [2.3522, 48.8566],
  zoom: 5
});
let marker, timeout;
const input = document.getElementById('search-box');
const results = document.getElementById('results');
input.addEventListener('input', () => {
  clearTimeout(timeout);
  const q = input.value.trim();
  if (q.length < 3) { results.style.display = 'none'; return; }
  timeout = setTimeout(async () => {
    const res = await fetch('https://api.maptiler.com/geocoding/' + encodeURIComponent(q) + '.json?key=YOUR_MAPTILER_KEY&limit=5');
    const data = await res.json();
    results.innerHTML = '';
    results.style.display = data.features.length ? 'block' : 'none';
    data.features.forEach(f => {
      const div = document.createElement('div');
      div.textContent = f.place_name;
      div.onclick = () => {
        const [lng, lat] = f.center;
        if (marker) marker.remove();
        marker = new maptilersdk.Marker({ color: '#9C27B0' }).setLngLat([lng, lat]).addTo(map);
        new maptilersdk.Popup().setLngLat([lng, lat]).setHTML('<b>' + f.place_name + '</b>').addTo(map);
        map.flyTo({ center: [lng, lat], zoom: 14 });
        results.style.display = 'none';
        input.value = f.place_name;
      };
      results.appendChild(div);
    });
  }, 300);
});

</script>
</body>
</html>

import * as maptilersdk from '@maptiler/sdk';
import '@maptiler/sdk/dist/maptiler-sdk.css';

maptilersdk.config.apiKey = 'YOUR_MAPTILER_KEY';
const map = new maptilersdk.Map({
  container: 'map',
  style: maptilersdk.MapStyle.STREETS,
  center: [2.3522, 48.8566],
  zoom: 5
});
let marker, timeout;
const input = document.getElementById('search-box');
const results = document.getElementById('results');
input.addEventListener('input', () => {
  clearTimeout(timeout);
  const q = input.value.trim();
  if (q.length < 3) { results.style.display = 'none'; return; }
  timeout = setTimeout(async () => {
    const res = await fetch('https://api.maptiler.com/geocoding/' + encodeURIComponent(q) + '.json?key=YOUR_MAPTILER_KEY&limit=5');
    const data = await res.json();
    results.innerHTML = '';
    results.style.display = data.features.length ? 'block' : 'none';
    data.features.forEach(f => {
      const div = document.createElement('div');
      div.textContent = f.place_name;
      div.onclick = () => {
        const [lng, lat] = f.center;
        if (marker) marker.remove();
        marker = new maptilersdk.Marker({ color: '#9C27B0' }).setLngLat([lng, lat]).addTo(map);
        new maptilersdk.Popup().setLngLat([lng, lat]).setHTML('<b>' + f.place_name + '</b>').addTo(map);
        map.flyTo({ center: [lng, lat], zoom: 14 });
        results.style.display = 'none';
        input.value = f.place_name;
      };
      results.appendChild(div);
    });
  }, 300);
});

How it works

The MapTiler Geocoding API accepts a text query and returns matching places with coordinates. As the user types (minimum 3 characters), a debounced request fires after 300ms of inactivity and populates a dropdown with up to 5 matching results.

Each feature has a center property with [lng, lat] coordinates. Clicking a result places a purple marker, shows a popup, and flies the map to zoom level 14. The dropdown hides and the input updates with the selected place name.

The GeocodingControl widget is a separate package: this example uses the REST API directly with fetch() for simplicity.

Key APIs

API	Description	Docs
Geocoding API	Forward geocoding REST endpoint	docs.maptiler.com/cloud/api/geocoding/
`map.flyTo()`	Animate to a new position	docs.maptiler.com/sdk-js/api/
`encodeURIComponent`	URL-encode the search query	MDN

FAQ

Can I limit results to a specific country?

Yes. Add &country=fr to the URL to restrict results to France. Multiple countries can be comma-separated.

How many results does the API return?

By default, up to 5 features. Add &limit=10 to get more (maximum 10).

Common mistakes

Using the GeocodingControl package without installing it separately: it is NOT in the SDK UMD bundle
Forgetting encodeURIComponent: place names with spaces or special characters break the URL
Not checking for empty results: the features array may be empty for ambiguous queries

auto_awesome

Build maps using MapTiler SDK with AI

Generate code like this address search with maptiler sdk example using the MapTiler SDK skill in your IDE.

auto_awesomeGet skills keyGet a free API key

Related Examples

Reverse Geocoding with MapTiler SDK
See how to do this in Leaflet, MapLibre GL JS or OpenLayers