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 Cloud 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 Cloud 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
- Please get in contact with Sales, describe your use case, and consult the Pricing page.
- You will be provided with a pre-activated binary for off-line use cases.
- 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.
Data Dashboard - Server tab - Pre-activated Binary
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’.
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’.
Geocoding folder includes indexes folder
3. The ‘indexes’ folder looks like this.
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/v2.0.3/maptiler-sdk.umd.min.js"></script>
<link href="https://cdn.maptiler.com/maptiler-sdk-js/v2.0.3/maptiler-sdk.css" rel="stylesheet" />
<script src="https://cdn.maptiler.com/maptiler-geocoding-control/v1.3.2/maptilersdk.umd.js"></script>
<link href="https://cdn.maptiler.com/maptiler-geocoding-control/v1.3.2/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 includeindexes
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.
Comments
0 comments
Please sign in to leave a comment.