Traccar Geocoder

A fast, self-hosted reverse geocoding service built from OpenStreetMap data. Given latitude and longitude coordinates, it returns the nearest street address including house number, street name, city, state, county, postcode, and country.

Part of the Traccar open source GPS tracking platform. Also available as a hosted service.

Features

• Street-level reverse geocoding from OSM data
• Address point, street name, and address interpolation lookup
• Administrative boundary resolution (country, state, county, city, postcode)
• Sub-millisecond query latency with memory-mapped index files
• Automatic HTTPS with Let's Encrypt
• Docker support with automatic PBF download and indexing

Quick Start

Docker Compose

services:
  geocoder:
    image: traccar/traccar-geocoder
    environment:
      - PBF_URLS=https://download.geofabrik.de/europe/monaco-latest.osm.pbf
    ports:
      - "3000:3000"
    volumes:
      - geocoder-data:/data

volumes:
  geocoder-data:

docker compose up

Docker

# All-in-one: download, build index, and serve
docker run -e PBF_URLS="https://download.geofabrik.de/europe-latest.osm.pbf" \
  -v geocoder-data:/data -p 3000:3000 traccar/traccar-geocoder

# Build index only
docker run -e PBF_URLS="https://download.geofabrik.de/europe-latest.osm.pbf" \
  -v geocoder-data:/data traccar/traccar-geocoder build

# Serve only (from pre-built index)
docker run -v geocoder-data:/data -p 3000:3000 traccar/traccar-geocoder serve

# Multiple PBF files
docker run -e PBF_URLS="https://download.geofabrik.de/europe/france-latest.osm.pbf https://download.geofabrik.de/europe/germany-latest.osm.pbf" \
  -v geocoder-data:/data -p 3000:3000 traccar/traccar-geocoder

# With automatic HTTPS
docker run -e PBF_URLS="https://planet.openstreetmap.org/pbf/planet-latest.osm.pbf" \
  -e DOMAIN=geocoder.example.com \
  -v geocoder-data:/data -p 443:443 traccar/traccar-geocoder

PBF files can be downloaded from Geofabrik.

API

GET /reverse

Query parameters:

• lat - latitude (required)
• lon - longitude (required)
• key - API key (required)

Example request:

GET /reverse?lat=43.7384&lon=7.4246&key=YOUR_API_KEY

Response follows Nominatim format:

{
  "display_name": "Avenue de la Costa 42, 98000 Monaco, Monaco",
  "address": {
    "house_number": "42",
    "road": "Avenue de la Costa",
    "city": "Monaco",
    "state": "Monaco",
    "county": "Monaco",
    "postcode": "98000",
    "country": "Monaco",
    "country_code": "MC"
  }
}

Fields are omitted when not available.

Status codes:

• 200 - success
• 401 - missing or invalid API key
• 429 - rate limit exceeded

Authentication

The server includes a web dashboard for managing API keys. On first launch, navigate to the server URL in a browser to create an admin account. Once logged in, you can generate API keys and create additional users with configurable rate limits.

Architecture

The project consists of two components:

• Builder (C++) - Parses OSM PBF files and creates a compact binary index using S2 geometry cells for spatial lookup.
• Server (Rust) - Memory-maps the index files and serves queries via HTTP/HTTPS with sub-millisecond latency.

Index Structure

The builder produces 14 binary files:

Building from Source

Prerequisites

Builder (C++):

• CMake 3.16+
• C++17 compiler
• libosmium, protozero, s2geometry, zlib, bzip2, expat

Server (Rust):

• Rust toolchain

Build

# Build the indexer
mkdir build && cd build && cmake ../builder && make

# Build the server
cargo build --release --manifest-path server/Cargo.toml

Run

# Create index from PBF file
./build/build-index output-dir input.osm.pbf [input2.osm.pbf ...]

# Start the server
./server/target/release/query-server output-dir [bind-address]

# Start with automatic HTTPS
./server/target/release/query-server output-dir --domain geocoder.example.com

Environment Variables (Docker)

License

Apache License, Version 2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.