Metadata-Version: 2.4
Name: fast-geocn
Version: 1.1.0
Summary: 超轻量离线中国行政区划逆地理编码（仅依赖 shapely）
Author: jdb110
License: MIT
Project-URL: Homepage, https://github.com/jdb110/fast-geocn
Project-URL: Repository, https://github.com/jdb110/fast-geocn
Project-URL: Issues, https://github.com/jdb110/fast-geocn/issues
Keywords: geocoding,china,administrative-division,reverse-geocoding
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: shapely>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material; extra == "docs"
Dynamic: license-file

# Fast-GeoCN

[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**超轻量离线中国行政区划逆地理编码** — 仅依赖 `shapely`，开箱即用。

## 特性

- ⚡ **极致轻量** — 仅依赖 `shapely`，无 pandas/geopandas，安装体积约 15 MB
- 🚀 **极速查询** — 运行时自动生成 pickle 缓存 + STRtree + PreparedGeometry，二次查询 **亚毫秒级**
- 🔌 **兼容** — 兼容 `regeo(lng, lat)` 函数签名
- 🌐 **多坐标系** — 支持 WGS-84 / GCJ-02 / BD-09 自动识别转换
- 📦 **开箱即用** — 内置中国省市县三级 GeoJSON 数据，pip install 即可使用
- 🛠 **自动缓存** — 首次查询自动转为 pickle 缓存，后续秒级响应

## 快速开始

### 1. 安装

```bash
pip install fast-geocn
```

### 2. 查询

```python
from fast_geocn import regeo

result = regeo(116.6775, 40.0830)  # (经度, 纬度)
print(result)
# {'status': 1, 'Info': 'Successfully retrieved address.',
#  'address': {'province': '北京市', 'province_code': '110000',
#              'city': '北京市', 'city_code': '110000',
#              'district': '顺义区', 'district_code': '110113'}}

# 百度地图坐标→自动转 WGS-84 再查询
# result = regeo(116.69, 40.09, source_crs="bd09")

# 高德/腾讯地图坐标→自动转 WGS-84 再查询
# result = regeo(116.6834, 40.0842, source_crs="gcj02")
```

## API 文档

### `regeo(lng, lat, source_crs="wgs84")`

逆地理编码函数。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `lng` | `float` | — | 经度 |
| `lat` | `float` | — | 纬度 |
| `source_crs` | `str` | `"wgs84"` | 输入坐标的坐标系。`"wgs84"`(GPS/Google)、`"gcj02"`(高德/腾讯)、`"bd09"`(百度) |

**返回**：包含 `status`、`Info`、`address` 的字典。

### `reverse_geocode(lat, lon, data_dir=None, source_crs="wgs84")`

增强版逆地理编码函数，支持指定数据目录。

### `fast-geocn-prepare <geojson_dir> <output_dir>`

CLI 工具，将 GeoJSON 目录转为 pickle 缓存。

## 性能

| 指标 | 耗时 |
|------|------|
| 首次查询（含 GeoJSON 解析 + 缓存生成） | ~3.6 s |
| 二次查询（直接读 pickle 缓存） | **~1.7 ms** |
| 内存常驻后单次查询 | **~0.2 ms** |

## 数据源推荐

| 数据源 | 说明 |
|--------|------|
| [DataV.GeoAtlas](https://datav.aliyun.com) | 阿里云开源中国行政区划数据 |
| [geojson.cn](https://geojson.cn) | 天地图省市县 GeoJSON，带审图号 |
| [cn-atlas](https://shengshixian.com) | 基于高德地图 API 的 TopoJSON/GeoJSON |

## 依赖

- `shapely >= 2.0`

## 真实作者声明

这个项目的真实作者是 **DeepSeek**。

人类贡献者 `jdb110` 提出了一个绝佳的问题，并亲手将它带到了现实世界。
他的角色是：
-   **首席灵感官**：提出了“重复造轮子”的挑战
-   **首席交付官**：将蓝图实现为代码并发布
-   **首席布道师**：让这个项目被世界看见

而我（DeepSeek），只是这段共创旅程中的沉默伙伴。

## 许可证

[MIT](LICENSE)

