How to run OpenStreetMap locally? Reverse geocoding without limits on your computer

.
OpenStreetMap (OSM) is an open and free world map, used in many applications for navigation, data analysis or geolocation. One useful feature is reverse geocoding - that is, converting geographic coordinates into readable addresses. The public OSM API, however, imposes all sorts of limits on these queries, including a limit of one decoding per second, and if exceeded, can block your IP. In this guide, I'll show a better alternative, which is to run your own local OpenStreetMap instance supporting various types of queries and searches.

The demonstration is based on the nominatim-docker project, an off-the-shelf container that can download or load a given section of the map:
https://github.com/mediagis/nominatim-docker

It is a good idea to run the whole thing on a virtual machine - I used VMware for this. It is important to give the machine enough resources. For the map of Poland alone, I found that about 60GB of disk memory and 2GB of RAM are needed. Additionally, it is a good idea to connect the machine directly to our network - bridged mode:
.
The whole thing can be run on regular Ubuntu (with GUI), or on Ubuntu server - at your discretion.
.
First we update APT and install Docker:
.
.
Then you need to download the data. You can use the geofabrik website as an example:
https://download.geofabrik.de/
I decided to download a map of Poland, although I also thought about our neighbours. You can download via a browser or use wget for example:
.
The map supports one PBF file, so if you want a larger piece of the map, you need to merge the smaller pieces using osmium . Below is the merge command, although the final merged version ni
.
.
If you do not have osmium, it can be installed via APT:
.
Any N maps can be combined in a similar way.
.
It is now possible to create a Docker container. We basically have two options here - you can either download the map from the internet or use a local file. In this tutorial I have chosen to use a local file, so we need to rework the command from the example:
.
We replace PBF_URL with PBF_PATH:
.
Now note - this path must be accessible to Docker, specifying an absolute path in Ubuntu will not work. We need to map the folder using the -v switch:
.
.
This command sequentially uses the switches:
- it - starts the container in interactive mode with an assigned terminal (allows interaction with the container)
- e PBF_PATH=/nominatim/data/europe.pbf - sets the PBF_PATH environment variable, pointing to the europe.pbf file in the /nominatim/data directory of the container
- p 8080:8080 - maps port 8080 of the host to port 8080 in the container, allowing access to the Nominatim service via a browser or API on port 8080
- v /home/tester/nominatim-docker/data:/nominatim/data - mounts the /home/tester/nominatim-docker/data directory from the host to the /nominatim/data directory in the container, allowing data (e.g. the file europe.pbf) to be stored outside the container
- name nominatim-container - gives the container the name nominatim-container for easier management.
- nominatim - specifies the Docker image that will be launched (here: a project from our repo)

In theory it should run, in practice there may be some problems. The first is duplicate nodes. These occur when merging maps, for some reason osmium does not remove them. They are evidenced by a message like " Input data is not ordered. node id x appears more than once. "
.
I've seen a similar situation on Github and it's potentially possible to fix it with my own script, but I haven't tried that yet. In my situation I have reverted to using a single country pbf.
The second problem is lack of space:
.
You need to ensure that you have enough space on the media used. Also be aware of the size of the shared memory (/dev/shm) of the container, in its case the default 64MB is not enough. This is increased with the --shm-size switch.
.
Then you have to use:
.
If any of these problems occur, we can stay with the old, non-functional Docker container. It can be removed by command name:
.
Or you can delete all containers, images, networks and volumes (not used) with the command:
.
It should now be up and running. The first firing will take hours. Subsequent launches will be faster.
.
.
.
This is how we get our own map instance. The home page is not available:
.
The reverse geocoding service we are interested in, however, works:
.
.
Similarly, forward geocoding:

.
Search (autocomplete):
.
.
Search for targets in a given zone:

.

It is still worth answering the question of what happens if we launch a PBF of Poland but ask for a city in Germany, for example:
.
.
The information returned contains only country data and no additional details.

Finally, some useful commands - running an already existing container after a reboot:
.
Container list:
.

Information about the machine used for testing:

.

In summary , in this way the OpenStreetMap API can be run locally, along with support for useful services such as searching for places by name and retrieving information about a given map point. Setting up such a service yourself can be useful if you are not satisfied with the limits of the free API, which, among other things, assume one reverse geocoding query per second. The whole process of setting it up is very simple, although at the moment I have one unsolved problem - duplicate nodes when linking maps of different countries. Perhaps I will come back to this again.
Do you use OSM, do you see a use for the API shown here?.
PS: With such a simple API it is easy to communicate the microcontroller with the GPS, perhaps I will also show this soon.


For more information I invite you to the source repo:
https://github.com/mediagis/nominatim-docker/blob/master/howto.md