Set up on-prem geocoding (place search)

Geocoding makes it possible to search your maps. We provide the functionality from our cloud but it’s also possible to self-host it, and this page explains how.

The key component of the search functionality is a geocoding index – a data structure that stores the attributes of all searchable locations. At MapTiler, we have professionally maintained geocoding indexes for the whole world, and you can use them via our online Geocoding API. To use them on-prem or completely offline, you need to set them up in your self-hosted environment. By doing that, you’ll get an on-prem Geocoding API which works just like the online one, and you can use it to add a search box (geocoding control) to your local maps.

Before you start

Before you get to the geocoding setup itself, make sure that MapTiler Server is installed and you have some maps ready. If you need help with these tasks, follow the 👉 Getting started with MapTiler Server guide.

Technical requirements

The geocoding service will run smoothly on a hosting machine with the following parameters:

4+ GB RAM
100+ GB of free HDD space for global geocoding indexes

For complete specs, see the MapTiler Server technical specification.

Set up the endpoint

First, let’s set up the on-prem Geocoding API endpoint. We’ll use a sample geocoding index, which is much smaller than full global indexes and thus more suitable for testing. The sample index only works for Switzerland, so you can test it together with the sample package which contains map data for the Zurich area in Switzerland.

When you get the full index for the whole world, you can set it up by following the same steps.

Go to your MapTiler Server administration Geocoding page.
Get a sample geocoding index: Use the Try geocoding button, or open the Downloads page in your MapTiler account manually. You’ll find the sample index under Free datasets. Download it to your local drive.
Upload the sample index to MapTiler Server: Use the Import index file button, or just drag & drop the file onto the page. (Do not extract the tar.gz archive before uploading!) MapTiler Server sets it up automatically and your local geocoding API endpoint is ready.

Test the endpoint

The local geocoding API endpoint is available in the /api/geocoding/ path. You can test it using wget or curl commands:

Save the JSON file to the folder where MapTiler Server is running:

   wget -o - http://localhost:3650/api/geocoding/zurich.json

Print the file contents to standard output:

   wget -O - http://localhost:3650/api/geocoding/zurich.json

To test in the browser, go to http://localhost:3650/api/geocoding/zurich.json.

Add search to your map

The on-prem geocoding functionality is completely independent of the on-prem maps. This means that the setup gives you the API endpoint, but doesn’t automatically add the search to your local maps. Instead, you get sample code to help you integrate the search control into any map application. Let’s see how to do that.

Select a basemap style: Use the dropdown menu to pick any of the maps hosted in MapTiler Server. This will be the basemap to show the search box on. The sample code for your map app will contain a link to this map style, which you can simply replace when you want to use a different map.
Configure the search: The geocoding feature and the control (aka search box) has plenty of config options, which you can adjust in the right panel. To learn more about the options, see the tooltips and Geocoding Control module documentation.
Use the provided sample code to add a search box to your map. The code updates itself dynamically when you make changes in the config panel, so once you’re happy with the settings, the code is ready too. There are two options, both using the MapTiler SDK JS:
- NPM Module code to add the geocoding control to your Node.js project. Start by using the first provided code block to install the SDK and geocoding control, then include the second code block in your JavaScript file.
- Basic JavaScript with complete code for a simple web map application. To use it, copy the code, paste it into a code editor or plain text editor, and save it as a .html file. Test it by opening in your web browser.

Remember that if you're using maps with sample data instead of the full data and a sample geocoding index instead of the full index, you'll only get a sample map application too – with a clipped map and limited search. Specifically, you'll be only able to search for places in Switzerland, and the map will only load if the searched place is in the Zurich area.

If you want to use a specific framework or another map library to implement the search box in your map app, you need to modify the code accordingly. We have a complete set of tutorials and code examples for various libraries using the online Geocoding API, which you can check out and adapt for on-prem use.

Offline use

You may notice that the code refers to online stylesheets and scripts from our SDK, meaning it won’t work when fully offline. To update it for offline use, you need to download the dependencies and replace URLs in the file header with local paths to the downloaded files. For example, in the basic JavaScript code, you’d replace <link href="https://cdn.maptiler.com/maptiler-sdk-js/v3.3.0/maptiler-sdk.css" rel="stylesheet"> with <link href="path/to/maptiler-sdk.css" rel="stylesheet">, replacing path/to/ with the relative path to the file in your project directory.

When downloading any dependencies for local use, note the version listed in the sample code and preferably get this exact version. These versions are tested. Different minor versions should work as well but it’s not guaranteed, and different major versions are usually not compatible.

What’s next: Get full index

Once you’ve tested on-prem geocoding using the sample index limited to Switzerland, you may want to get a full index for the whole world. If your license doesn’t include on-prem geocoding, first contact our Sales team to arrange it. The global indexes will be then available on the Downloads page in your MapTiler account.