reverse-geocoder-cn 0.1.0

离线为中国的区县进行逆地理编码;Offline reverse geocoding for Chinese province, city and county boundaries
Documentation

reverse-geocoder-cn

一个纯 Rust 的中国离线逆地理编码库。支持十进制度数和“度 + 十进制分”两种输入,返回省、市、区县及六位行政区划码;运行时只读取本地 cn_admin.bin,不会访问 API 或网络。

crate 随包附带已生成的 cn_admin.bin,普通使用者无需下载或构建数据。项目中的 cn_geojson/ 仅用于在行政区划更新后重新生成该二进制文件。

使用

应用中直接加载随 crate 编译的二进制数据并查询:

use reverse_geocoder_cn::ReverseGeocoder;

let geocoder = ReverseGeocoder::embedded()?;
let result = geocoder.reverse_geocode(39.9087, 116.3975).unwrap();

assert_eq!(result.county.name, "东城区");
println!("{} {} {} ({})", result.province.name, result.city.name, result.county.name, result.county.code);

度分坐标分别作为纬度、经度两个参数传入:

let result = geocoder
    .reverse_geocode_degree_minutes("42°16.9552000'N", "126°36.5127000'E")?
    .unwrap();

assert_eq!(result.county.name, "靖宇县");

reverse_geocode 返回 Option<Address>;reverse_geocode_degree_minutes 返回 Result<Option<Address>, CoordinateParseError>,度分格式不合法时为 Err。两种方法在坐标位于中国边界之外时都返回 None/Ok(None)。

完整的最小示例见 examples/minimal.rs,运行:

cargo run --release --example minimal

分发

ReverseGeocoder::embedded() 使用随库发布的 cn_admin.bin,适合绝大多数情况。数据会被编译进调用方的二进制文件,因此部署时无需额外拷贝数据文件。

如果希望自行管理数据文件,可改用:

let geocoder = ReverseGeocoder::open("/path/to/cn_admin.bin")?;

二进制保存全部三层行政区边界。库在加载时为各层建立 R-tree 包围盒索引,随后使用精确的点落多边形判断,因此并非“最近区县中心点”近似匹配。

更新或自行构建数据

  1. 从天地图行政区划数据下载省、市、县三级 GeoJSON。
  2. 放到 cn_geojson/ 目录,文件名分别为 中国_省.geojson、中国_市.geojson、中国_县.geojson。
  3. 运行:
cargo run --release --bin build-data -- cn_geojson cn_admin.bin

新生成的 cn_admin.bin 可通过 ReverseGeocoder::open 加载;要更新随库发布的默认数据,直接替换仓库根目录的同名文件后重新发布 crate。

数据与坐标注意事项

  • 两种方法的参数顺序均为纬度、经度。
  • 度分形式的两个参数例如 "42°16.9552000'N"、"126°36.5127000'E"。
  • 源数据坐标必须与输入坐标使用同一坐标系。所给数据为 CGCS2000(通常与 GPS/WGS-84 足够接近);GCJ-02、BD-09 坐标须先转换。
  • 行政区划会调整。更新 cn_geojson/ 后,重新执行 build-data 即可生成新的分发文件。
  • gb 属性中的 156 国家前缀会移除,结果例如 110101。

数据来源

随库分发的边界数据来自天地图行政区划数据。

许可证

代码采用 MIT OR Apache-2.0 双许可证。