On-premises geocoding in MapTiler Server

MapTiler Geocoding service

The MapTiler Geocoding API, together with the MapTiler SDK Geocoding Control, enables map developers to add the possibility of forward and reverse geocoding to their mapping applications. The Geocoding service API is part of the MapTiler API.

The Geocoding API supports, among others:

  • Multi-lingual search
  • Proximity-based search results
  • Bounding box or country-limited search
  • Fuzzy matching
  • Autocomplete

Search index type limitations, such as Address points, Countries, POIs, and many more.

MapTiler SDK Geocoding Control is designed for effortless integration into React and Svelte applications. With just a single line of code, you can incorporate a reliable all-in-one place and address search box into your applications. It is integrated with React and Svelte and can also be used as Vanilla JavaScript.

On-premise Geocoding by MapTiler (BETA)

On-premise Geocoding can be part of the MapTiler Server. With MapTiler Server, you will get the same functionality and database we provide in the MapTiler API. You may test the Geocoding service on our Geocoding product page or the MapTiler Maps showcase. The Geocoding is not part of the standard MapTiler Server download page, you may contact our Sales directly for being provided with MapTiler Server package with Geocoding enabled API in side.

Supported environments

For now, on-premise Geocoding is supported only on Linux machines. We support Debian and Ubuntu distributions (DEB-based) and Fedora (RPM-based).

MacOS or Windows operating systems are not supported at the moment.

Getting on-premise Geocoding for MapTiler Server

  1. Please get in contact with Sales, describe your use case, and consult the Pricing page.
  2. You will be provided with a pre-activated binary for off-line use cases.
  3. Geocoding is part of RPM or DEB packages that are suitable for your Linux distribution.

Dependencies and requirements

Internally, Geocoding needs at least a Node 18 environment.
The server should have at least 4GB of RAM and 100GB of free HDD space for the global indexes.

Installation

Install MapTiler Server

You received an email with a download link for your binary. Otherwise, you can find it in your Data Dashboard Server→:appropriate license key → detail → Download Link.

1.png
Data Dashboard - Server tab - Pre-activated Binary

2.png
Subscription detail with download link and binary expiration date

After downloading the binary, installing should be straight-forward. Check the MapTiler Server documentation for more details.

AppImage example:

chmod 755 maptiler-server-4.5.1-XXX-linux.AppImage  
./maptiler-server-4.5.1-XXX-linux.AppImage

Install Geocoding indexes

Before starting the Server, the geocoding database (aka Indexes) must be downloaded and unpacked to the target location. You can copy indexes to the destination location any time later, but the server has to be restarted.

You were provided with a download link in the email. This will start downloading a TAR archive.

After downloading, you must unpack them in the MapTiler Server work directory. You can do this either in the terminal or in the file explorer. Please ensure that the folders are named exactly as shown in the example; otherwise, Geocoding won’t function correctly.

In the terminal:

mkdir -p <SERVER_WORK_DIR>/geocoding  
cp indexes-2.12.1.tar.gz <SERVER_WORK_DIR>/geocoding/  
cd <SERVER_WORK_DIR>/geocoding/  
tar -xzf indexes-2.12.1.tar.gz  
ls <SERVER_WORK_DIR>/geocoding/indexes/

In the file explorer:

1. In your work directory (e.g./home/usr/Documents/maptiler-server) create a folder called  ‘geocoding’.

3.png
Work directory includes the folder called “geocoding”

2. Extract the downloaded TAR archive in the newly created folder. It will create a folder called ‘indexes’.

4.png
Geocoding folder includes indexes folder

3. The ‘indexes’ folder looks like this.

5.png Indexes folder contains downloaded data

Starting MapTiler Server

MapTiler Server is to be started with the command maptiler-server:

cd <SERVER_WORK_DIR>  
maptiler-server

After any manipulation with the geocoding indexes, MapTiler Server needs to be restarted to apply the changes.

Testing Geocoding

The Geocoding API is available in the/api/geocoding/ path, test it for example using wget or curl commands:

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

Or in the browser insert URL: http://localhost:3650/api/geocoding/zurich.json.

Check the Geocoding API documentation.

Adding Geocoding Control to maps

For adding Geocoding Control into Maps, you may follow our standard documentation. The simplest Vanilla JavaScript code using MapTiler SDK could look as the following example:

<!DOCTYPE html>  
<html lang="en">  
<head>  
<meta charset="UTF-8">  
<meta name="viewport" content="width=device-width, initial-scale=1.0">  
<title>Display a Geocoding Control</title>  
<script src="https://cdn.maptiler.com/maptiler-sdk-js/v3.5.0/maptiler-sdk.umd.min.js"></script>  
<link href="https://cdn.maptiler.com/maptiler-sdk-js/v3.5.0/maptiler-sdk.css" rel="stylesheet" />  
<script src="https://cdn.maptiler.com/maptiler-geocoding-control/v2.1.7/maptilersdk.umd.js"></script>  
<link href="https://cdn.maptiler.com/maptiler-geocoding-control/v2.1.7/style.css" rel="stylesheet">  
<style>  
body { margin: 0; padding: 0; font-family: sans-serif; }  
#map { position: absolute; top: 0; bottom: 0; width: 100%; }  
</style>  
</head>  
<body>  
<div id="map"></div>  
<script>  
const map = (window.map = new maptilersdk.Map({  
container: 'map', // container's id or the HTML element to render the map  
style: "http://localhost:3650/maps/yourmap/style.json", // stylesheet location  
zoom: 3,  
center: [-94.77, 38.57],  
}));  
const gc = new maptilersdkMaptilerGeocoder.GeocodingControl({  
apiUrl: "http://localhost:3650/api/geocoding"  
});  
map.addControl(gc, 'top-left');  
</script>  
</body>  
</html>

Troubleshooting

When you see one of following messages after the MapTiler Server starts:

“Please provide a valid data for geocoding service and restart MapTiler Server.”

  • An existing geocoding folder must be in the working directory. This directory must include indexes folder with its data.
  • This folder is read only during the app’s start; therefore, MapTiler Server needs to be restarted to apply any changes.

“Geocoding service libraries cannot be loaded.”

  • This binary does not include geocoding libraries. Special binaries are required in these libraries.
  • Please get in touch with Sales to obtain pre-activated server binaries with Geocoding enabled.

“Your version of MapTiler Server does not currently support the Geocoding service. Please contact MapTiler Sales for more information and licensing options.”

  • The license does not support geocoding. You must have an active license with a checked geocoding flag. Contact our sales.

“Geocoding service is not supported on your platform. We are working on enabling it in future versions, in the meantime, you can use docker distribution.”

  • Geocoding is supported only on Linux distributions based on Node 18 and glibc 2.28 or higher.
  • Tested Linux distributions: Debian 10, Ubuntu 20.04 and 22.04, and Fedora 37. Docker Tested.
  • Geocoding service is not supported on Windows and macOS.