maptiler/maptiler-geocoding-control

The Javascript & TypeScript Map Control component for MapTiler Geocoding service! Easy to be integrated into any JavaScript mapping application.

official page →

The Javascript & TypeScript Map Control component for MapTiler Geocoding service! Easy to be integrated into any JavaScript mapping application.

MapTiler Geocoding control for MapTiler SDK, MapLibre GL JS, Leaflet and OpenLayers

About

A Geocoding control for MapTiler SDK, MapLibre GL JS and Leaflet utilizes MapTiler Cloud Geocoding API. With this control, users of mapping application can find any place on Earth (States, Cities, Streets, Addresses, POIs, ...) down to the address level, restrict the search area to a specific country, highlight searched results on the map, autocomplete words while typing, and much more.

The component can be used as an ES module or UMD module with or without bundler.

Geocoding control is also provided as React component and Svelte component and other libraries.

Quick start

Install the Geocoding control unsing npm:

npm install --save @maptiler/geocoding-control @maptiler/sdk

Use the component in your mapping application:

import * as maptilersdk from "@maptiler/sdk";
import { GeocodingControl } from "@maptiler/geocoding-control/maptilersdk";
import "@maptiler/sdk/dist/maptiler-sdk.css";
import "@maptiler/geocoding-control/style.css";

maptilersdk.config.apiKey = "YOUR_MAPTILER_API_KEY_HERE";

const map = new maptilersdk.Map({
  container: "map", // id of HTML container element
});

const gc = new GeocodingControl();

map.addControl(gc);

NOTE: Get your personal MapTiler API key in the MapTiler Cloud.

Installation and more usage examples

• With MapTiler SDK
• With MapLibre GL
• With Leaflet
• With OpenLayers
• As a React component
• As Svelte component
• As vanilla JavaScript module

API Documentation

In addition to the details and examples provided in this README.md and our documentation, check out

• The complete Geocoding service API documentation
• The complete Geocoding control reference
• UMD global variables

Development

Building

npm install && npm run build

You will find compilation result in the dist directory.

Running in dev mode

npm install && VITE_API_KEY=YOUR_MAPTILER_API_KEY_HERE npm run dev

POI icons and bundlers

POI icons are served from CDN per default. If there is an requirement to serve them from a different location and the control is used in the application which is build with Web Application bundler (like Webpack or Vite) then it is necessary to do some extra configuration. Icons are bundled in the library and you can find them in node_modules/@maptiler/geocoding-control/icons. Configure your bundler and/or provide iconsBaseUrl option for the icons to be properly resolved. You can also copy icons from that directory to your public directory.

maptiler-geocoding-control's Issues

[BUG] Collapsed GeocodingControl icon width is 34px (should be 33px)

Describe the bug
Collapsed GeocodingControl icon width is 34px which is inconsistent with the rest of the MapTiler's icons (which all have 33px width).

To Reproduce
Browser: Chrome

Code:

      const geocodingControl = new maptilersdkMaptilerGeocoder.GeocodingControl({
          collapsed: true
      });

      const map = new maptilersdk.Map({
          container: 'map',
          style: maptilersdk.MapStyle.BACKDROP,
          zoom: 1,
          center: [-15.5, 15.2],
          hash: true,
          maptilerLogo: false,
          maxBounds: [[-178, -80], [178, 80]]
      });

      map.addControl(geocodingControl, 'top-right');

Expected behavior
The width should be 33px, consistent with the rest of the icons.

Screenshots

[FEATURE] return `continent` for the geocoded results

Is your feature request related to a problem? Please describe.
When I geocode a point, I also need to obtain the continent [Asia|Africa|North America|South America|Antarctica|Europe|Oceania]

Describe the solution you'd like
Add continent to the returned results and to the type filter.

Describe alternatives you've considered
Search within a custom built array of countries-continents pair or double geocode the point or country with another service (😥)

Additional context
Oceania has a sort of blurred definition in some countries.
There could be some inconsistencies for certain countries with overseas territories (Spain's Ceuta, French Polynesia and many similar cases).
These are more of edge cases, and like with the regular geocoding, a standard needs to be found.
https://en.wikipedia.org/wiki/Continent

[BUG] Type incompatibility between this lib `Map` type and @maptiler/sdk `Map` type

Describe the bug
This title says it all, here is a screenshot of the exact error:

To Reproduce
Just follow the readme of this package.

Expected behavior
No type error.

Additional context
All packages are on their latest version.

[FEATURE] Support for maplibre GL JS v4

Is your feature request related to a problem? Please describe.
Maplibre GL JS v4 has been released. Currently the devDependencies and peerDependencies of this package are bound respectively to Maplibre GL JS ^3.6.2 and ^2 || ^3.0.0-alpha || ^3, preventing it from being used with v4-based apps (unless --force or --legacy-peer-dep is used during install)

Describe the solution you'd like
I would like to use this package with maplibre gl js v4 and the package.json to accept ^4 in addition to the existing supported versions.

Additional context
The list of breaking changes it includes is in https://github.com/maplibre/maplibre-gl-js/releases/tag/v4.0.0 .

[BUG] Geocoding control breaks OpenLayers map with useGeographic()

Description
When initializing an OpenLayers based map in conjunction with useGeographic() any result clicked from the search bar renders the map black and hence useless.

Steps to reproduce
To reproduce the issue, simply create a sample OpenLayers based map together with useGeographic() and instantiate the Geocoding control, type something into the search bar, click on the first result and watch the map black out.

Expected behavior
The Geocoding control should support OpenLayers maps with useGeographic() as well

Screenshots
If applicable, add screenshots to help explain your problem.

Update README file

Reorganize README, be more in line with MapTiler Client library

[BUG]not work in leaflet 1.7.1

Describe the bug
not work in leaflet 1.7.1

<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no" />
    <title>MapTiler Geocoding control</title>
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/leaflet.css" />
<script src="https://unpkg.com/[email protected]/dist/leaflet.js"></script>
  <script src="https://cdn.maptiler.com/maptiler-geocoding-control/v1.2.0/leaflet.umd.js"></script>
<link href="https://cdn.maptiler.com/maptiler-geocoding-control/v1.2.0/style.css" rel="stylesheet">  <style>
      #map {position: absolute; top: 0; right: 0; bottom: 0; left: 0;}
    </style>
  </head>
  <body>
    <div id="map">
      <a href="https://www.maptiler.com" style="position:absolute;left:10px;bottom:10px;z-index:999;"><img src="https://api.maptiler.com/resources/logo.svg" alt="MapTiler logo"></a>
    </div>
    <p><a href="https://www.maptiler.com/copyright/" target="_blank" rel="noopener">&copy; MapTiler</a> <a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">&copy; OpenStreetMap contributors</a></p>
    <script>
      const key = 'key';
      const map = L.map('map').setView([49.2125578, 16.62662018], 14); //starting position
  const layer = L.tileLayer(`https://api.maptiler.com/maps/streets-v2/{z}/{x}/{y}.png?key=${key}`,{
    tileSize: 512,
    zoomOffset: -1,
    minZoom: 1,
    attribution: "\u003ca href=\"https://www.maptiler.com/copyright/\" target=\"_blank\"\u003e\u0026copy; MapTiler\u003c/a\u003e \u003ca href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\"\u003e\u0026copy; OpenStreetMap contributors\u003c/a\u003e",
    crossOrigin: true
  }).addTo(map);
L.control.maptilerGeocoding({ apiKey: key }).addTo(map);
    </script>
  </body>
</html>

[BUG] Results not ordered by relevance

Describe the bug

The geocoding API results don't always seem to be returned with the most relevant results at the top. I'm not sure if this is a bug in the API or if the geocoding control should be doing some sort of results.sort(result => result.relevance)? Either way it means that sometimes less relevant results appear lower down in the list.

To Reproduce

API response: https://api.maptiler.com/geocoding/5%20frie.json?proximity=7.098955%2C50.736281&fuzzyMatch=true&key=xxx

Or load a map, navigate somewhere and search for the results

Expected behavior

The most relevant results should be at the top

Screenshots

Simplified API response for relevant bits:

[
  {
    "place_name": "Fries 5, 6641NR Beuningen, Netherlands",
    "relevance": 0.916667
  },
  {
    "place_name": "Furie 5, 3144DS Maassluis, Netherlands",
    "relevance": 0.916667
  },
  {
    "place_name": "Frei 5, 4681 Frei, Rottenbach, Austria",
    "relevance": 0.88
  },
  {
    "place_name": "Grie 5a, 31141 Hildesheim, Germany",
    "relevance": 0.88
  },
  {
    "place_name": "Frik 5, 1704DT Heerhugowaard, Netherlands",
    "relevance": 0.88
  },
  {
    "place_name": "Friedensplatz 5, 53111 Bonn, Germany",
    "relevance": 1
  },
  {
    "place_name": "Friedrichstraße 5, 53111 Bonn, Germany",
    "relevance": 1
  },
  {
    "place_name": "Friedrich-Wilhelm-Straße 5, 53113 Bonn, Germany",
    "relevance": 1
  },
  {
    "place_name": "Friedenstraße 5, 53229 Bonn, Germany",
    "relevance": 1
  },
  {
    "place_name": "Friedlandstraße 5, 53117 Bonn, Germany",
    "relevance": 1
  }
]

[BUG] Icons not loading in search results

Describe the bug
The icons associated with search results do not load. Instead, a placeholder text is shown.

To Reproduce
Error occurs on this demo page (and in my app) (firefox and chrome): https://docs.maptiler.com/sdk-js/examples/geocoder-component/
Works fine on this demo page: https://www.maptiler.com/cloud/geocoding/

Screenshots

Is it possible to disable icons completely (appropriate for my use case)? I did not find such a parameter option.

Add support to OpenLayers

Create a plugin for OpenLayers similar to the Leaflet

Can you add Nuxt 3 support?

[BUG] geocoding control component freezes after first search

Describe the bug

I have followed the tutorial at and the geocoding control component works great, but only on the first go.

To Reproduce

See reproducible example + video associated with a simple codebase showing this behaviour here cruse-bike/cruse#8

Expected behavior

I was expecting to be able to clear the search results and fly to another place after the first 'flyto'.

Screenshots

2023-11-30.10-23-22.mp4

Additional context

I'm experimenting with MapLibre and Svelte to add quality of life features (like geocoding) and UX improvements to this web application funded by the Irish Government for sustainable transport planning: https://cruse.bike/