Hyper-optimized reverse geocoding API

Source: Hacker News

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://download.geofabrik.de/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)

Response follows the 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.

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(s)
./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.