All posts
TraccarNominatimOpenStreetMapDocker

Self-hosted reverse geocoding for Traccar with Nominatim

Nov 16, 20265 min read

Traccar can show a street address for every position: in the web interface, in reports and in notifications ("Vehicle stopped at 12 Main Road"). Turning that address lookup on is called reverse geocoding, and it raises a question: which service answers those lookups?

The usual options:

  • Paid APIs (Google, Mapbox, HERE and others) are accurate, but charge per request. A busy fleet makes a lot of requests.
  • Free public servers, like the public OpenStreetMap Nominatim, have strict usage policies (around one request per second) that a fleet quickly exceeds. They're not meant for production tracking.
  • Your own server running Nominatim with OpenStreetMap data has no per-request cost and no rate limit, and your customers' locations never leave your infrastructure.

This post sets up the third option with Docker and connects it to Traccar.

How big a server do you need?

Nominatim imports OpenStreetMap data into a PostgreSQL database. The size depends almost entirely on which regions you import:

  • A single small or medium country is very manageable on a modest VPS.
  • A large country, a continent or the whole planet needs much more RAM and fast SSD storage, and the import can take hours or days.

Import only the regions where your devices actually operate. Regional extracts are available from Geofabrik (download.geofabrik.de), split by continent, country and often by state or zone.

Check the current hardware recommendations in the Nominatim documentation before buying a server, and keep geocoding on a separate server from Traccar for anything beyond a small region, so imports and heavy lookups don't slow down tracking.

1. Run Nominatim with Docker

The community-maintained mediagis/nominatim image does the import and serves the API in one container. Install Docker first if needed (curl -fsSL https://get.docker.com | sh).

Pick your region's .osm.pbf link from Geofabrik, then start the import:

docker run -d --name nominatim \
  --restart unless-stopped \
  --shm-size=1g \
  -e PBF_URL=https://download.geofabrik.de/asia/india/southern-zone-latest.osm.pbf \
  -e REPLICATION_URL=https://download.geofabrik.de/asia/india/southern-zone-updates/ \
  -e IMPORT_STYLE=address \
  -v nominatim-data:/var/lib/postgresql/16/main \
  -p 127.0.0.1:8080:8080 \
  mediagis/nominatim:4.4

What the options do:

  • PBF_URL: the map extract to import. Replace it with your region.
  • REPLICATION_URL: where to fetch updates, so new roads and addresses appear over time.
  • IMPORT_STYLE=address: imports only what's needed for addresses, which is smaller and faster than the full style. Enough for reverse geocoding.
  • -v nominatim-data:...: keeps the database in a Docker volume so it survives container restarts. Check the image's README for the exact data path for the version you use, since it changes with the PostgreSQL version.
  • -p 127.0.0.1:8080:8080: only reachable from this server. Your geocoder shouldn't be open to the internet.

Check the image's page on Docker Hub for the latest version tag and options.

Watch the import:

docker logs -f nominatim

When the logs show the server is listening, test a lookup with coordinates inside your region:

curl "http://127.0.0.1:8080/reverse?format=json&lat=13.0827&lon=80.2707"

You should get JSON with a display_name and an address object.

If Traccar runs on a different server, keep the port private and connect over a private network or VPN, or restrict access with a firewall rule that only allows the Traccar server's IP.

2. Connect Traccar

In /opt/traccar/conf/traccar.xml, add:

<entry key='geocoder.enable'>true</entry>
<entry key='geocoder.type'>nominatim</entry>
<entry key='geocoder.url'>http://127.0.0.1:8080/reverse</entry>

Restart Traccar:

sudo systemctl restart traccar

New positions now get an address. Open a device in the web interface, or run a report, to check.

3. Tune it

A few optional settings make a big difference on busy servers. Check the Traccar configuration documentation for the exact keys and defaults in your version:

<!-- Remember recent lookups in memory -->
<entry key='geocoder.cacheSize'>10000</entry>

<!-- Reuse the previous address if the device moved less than this many metres -->
<entry key='geocoder.reuseDistance'>50</entry>

<!-- Language of returned addresses -->
<entry key='geocoder.language'>en</entry>

geocoder.reuseDistance is especially useful. A parked vehicle reporting every 30 seconds would otherwise trigger a lookup each time, for the same address.

Traccar also lets you customise the address format, and choose to look up addresses only when they're needed (for example in reports) instead of for every position. Both are worth considering if your geocoder is under heavy load.

4. Keep the data fresh

OpenStreetMap changes constantly. With REPLICATION_URL set, the container can apply updates. See the image's README for how updates are scheduled. Check now and then that addresses for recently built areas appear.

What about Photon?

Photon is another open-source geocoder built on OpenStreetMap data. It's fast and has excellent search-as-you-type, and it can be lighter to run for some setups. For pure reverse geocoding in Traccar, Nominatim is the most common choice and is supported directly, but Photon is worth a look if you also need address search in your own apps.

Troubleshooting

Problem Check
No addresses in Traccar Is geocoder.enable true and Traccar restarted? Does the curl test work from the Traccar server?
Addresses only for some areas The position is outside the region you imported.
Import fails or stops Not enough RAM or disk. Check docker logs nominatim.
Slow lookups Add cache and reuse distance settings, or give the geocoder more RAM and SSD.

Summary

  1. Pick only the regions you need from Geofabrik.
  2. Run mediagis/nominatim with Docker, bound to localhost.
  3. Point Traccar at http://127.0.0.1:8080/reverse.
  4. Add caching and reuse distance to cut repeated lookups.

Want this set up for your fleet's regions, sized correctly and connected to Traccar? See my self-hosted geocoding server setup service.

Keep reading

Need help with your Traccar server?

I offer Traccar setup and maintenance, GPS tracking apps and Flutter development.