超优化的逆向地理编码 API

Source: Hacker News

一个基于 OpenStreetMap 数据的快速自托管逆向地理编码服务。给定纬度和经度坐标后，它会返回最近的街道地址，包括门牌号、街道名称、城市、州/省、县、邮政编码和国家。

是 Traccar 开源 GPS 跟踪平台的一部分。也提供 托管服务。

功能

• 基于 OSM 数据的街道级逆向地理编码
• 地址点、街道名称和地址插值查询
• 行政边界解析（国家、州/省、县、市、邮政编码）
• 使用内存映射索引文件实现亚毫秒查询延迟
• 自动使用 Let’s Encrypt 的 HTTPS
• Docker 支持，自动下载 PBF 并建立索引

快速入门

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

一体化：下载、构建索引并提供服务

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

仅构建索引

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

仅提供服务（使用预先构建的索引）

docker run -v geocoder-data:/data -p 3000:3000 traccar/traccar-geocoder serve

多个 PBF 文件

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

自动 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 文件可从 Geofabrik 下载。

API

GET /reverse

查询参数

• lat – 纬度（必填）
• lon – 经度（必填）

响应 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"
  }
}

当字段不可用时将被省略。

架构

该项目由两个组件组成：

• Builder（C++）——解析 OSM PBF 文件，并使用 S2 几何单元格创建紧凑的二进制索引以进行空间查找。
• Server（Rust）——内存映射索引文件，并通过 HTTP/HTTPS 提供查询，延迟低于毫秒。

索引结构

构建器会生成 14 个二进制文件：

从源码构建

前置条件

Builder (C++)

• CMake 3.16+
• C++17 编译器
• libosmium、protozero、s2geometry、zlib、bzip2、expat

Server (Rust)

• 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(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)

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.