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 编译的二进制数据并查询:

```rust
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);
```

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

```rust
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`](examples/minimal.rs),运行:

```bash
cargo run --release --example minimal
```

## 分发

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

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

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

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

## 更新或自行构建数据

1. 从[天地图行政区划数据]https://cloudcenter.tianditu.gov.cn/administrativeDivision下载省、市、县三级 GeoJSON。
2. 放到 `cn_geojson/` 目录,文件名分别为 `中国_省.geojson`、`中国_市.geojson`、`中国_县.geojson`。
3. 运行:

```bash
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`。

## 数据来源

随库分发的边界数据来自[天地图行政区划数据](https://cloudcenter.tianditu.gov.cn/administrativeDivision)。

## 许可证

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