原文
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.
- 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
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:# 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-geocoderPBF files can be downloaded from Geofabrik.
Query parameters:
lat- latitude (required)lon- longitude (required)
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.
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.
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++):
- CMake 3.16+
- C++17 compiler
- libosmium, protozero, s2geometry, zlib, bzip2, expat
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.