Windows CE apps were doing this 20 years ago with single file databases of only a few GBs, why do I need a 500GB+ postgres monster to do the same thing today?
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.
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
# 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.
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 - success401 - missing or invalid API key429 - rate limit exceededThe 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.
The project consists of two components:
The builder produces 14 binary files:
| File | Description |
|---|---|
geo_cells.bin |
Merged S2 cell index for streets, addresses, and interpolations |
street_entries.bin |
Street way IDs per cell |
street_ways.bin |
Street way headers (node offset, name) |
street_nodes.bin |
Street node coordinates |
addr_entries.bin |
Address point IDs per cell |
addr_points.bin |
Address point data (coordinates, house number, street) |
interp_entries.bin |
Interpolation way IDs per cell |
interp_ways.bin |
Interpolation way headers |
interp_nodes.bin |
Interpolation node coordinates |
admin_cells.bin |
S2 cell index for admin boundaries |
admin_entries.bin |
Admin polygon IDs per cell |
admin_polygons.bin |
Admin polygon metadata |
admin_vertices.bin |
Admin polygon vertices |
strings.bin |
Deduplicated string pool |
Builder (C++):
Server (Rust):
# Build the indexer
mkdir build && cd build && cmake ../builder && make
# Build the server
cargo build --release --manifest-path server/Cargo.toml
# 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
| Variable | Description | Default |
|---|---|---|
PBF_URLS |
Space-separated list of PBF download URLs | (required for auto/build) |
DOMAIN |
Domain name for automatic HTTPS via Let's Encrypt | (disabled) |
BIND_ADDR |
HTTP bind address | 0.0.0.0:3000 |
DATA_DIR |
Data directory for PBF files and index | /data |
CACHE_DIR |
ACME certificate cache directory | acme-cache |
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.