超优化的反向地理编码API

超优化的反向地理编码API
Hyper-optimized reverse geocoding API

原始链接: https://github.com/traccar/traccar-geocoder

## Traccar Geocoder：快速、自托管的反向地理编码 Traccar Geocoder 是一款高性能、自托管的反向地理编码服务，基于 OpenStreetMap (OSM) 数据构建。它能快速将经纬坐标转换为人类可读的地址——包括门牌号、街道、城市、州和国家——查询延迟低于毫秒级。该服务是 Traccar GPS 跟踪平台的核心组件，但也可独立使用，包括托管选项。它采用两部分架构：一个 C++ Builder 用于处理 OSM 数据（可从 Geofabrik 下载）并将其转换为紧凑的二进制索引，以及一个 Rust Server 用于通过 HTTP/HTTPS 高效地处理查询。借助 Docker 支持，部署流程已简化，提供自动 PBF 下载和索引、从预构建索引服务以及使用 Let's Encrypt 自动配置 HTTPS 的选项。配置通过环境变量管理，允许灵活自定义。响应格式与 Nominatim 相同，在可用时提供详细的地址信息。它采用 Apache 2.0 许可。

Traccar开发了一种新的、高度优化的反向地理编码API，在Hacker News上引发了讨论。该API使用C++和Rust构建，旨在通过将OpenStreetMap (OSM)数据解析为紧凑的二进制索引（使用S2几何）来实现亚毫秒级的查询延迟。它设计为自托管，并提供与Nominatim兼容的API，通过Docker自动启用HTTPS。虽然有些人质疑在Pelias等现有选项存在的情况下，是否需要另一个地理编码器，但其他人强调了潜在的好处，例如查询基本地址信息之外的详细特征，以及与大型语言模型集成。一个关键点是人们渴望易于自托管的*地理编码*（而不仅仅是反向地理编码）系统，并对当前与过去更简单的解决方案相比，数据库需求越来越大的趋势表示遗憾。

原文

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-geocoder

PBF 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

Environment Variables (Docker)

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.

超优化的反向地理编码API Hyper-optimized reverse geocoding API

Environment Variables (Docker)

超优化的反向地理编码API
Hyper-optimized reverse geocoding API