Address Geocoding

---
name: address-geocoding
description: "地址解析——把一批中文地址清洗、批量转成经纬度或反查地址、标出低可信行、算到门店的球面距离，接腾讯位置服务。当用户说「地址批量转经纬度」「坐标反查地址」「哪些订单在配送范围内」时使用。"
author: Captain
version: 0.1.0
display_name: "地址解析"
display_name_en: "Address Geocoding"
description_zh: "中文地址批量解析：清洗规则（补省市、去括号备注、全半角统一）、腾讯位置服务 WebService 地理编码与逆地址解析（key 从环境变量读，默认预演）、低可信与失败行标记、球面距离与配送半径、GCJ-02 与 WGS-84 坐标系提醒；附标准库脚本与本地模拟服务。"
description_en: "Batch-convert Chinese addresses to coordinates (or back) with the Tencent Location Service WebService API: address cleaning, dry-run by default, retries and caching, low-confidence flags, haversine distance to stores, and coordinate-system caveats."
tags:
  - "地址解析"
  - "地理编码"
  - "逆地址解析"
  - "经纬度"
  - "腾讯位置服务"
  - "配送范围"
  - "距离计算"
  - "坐标系"
  - "geocoding"
  - "reverse geocoding"
examples_zh:
  - "这 3000 个收货地址帮我做地址解析，批量转成经纬度，要在地图上打点"
  - "门店坐标有了，帮我算哪些订单在 3 公里配送范围内，地址解析不准的标出来"
  - "有一批经纬度，想坐标反查地址，用腾讯位置服务"
examples_en:
  - "Geocode 3,000 Chinese delivery addresses in a CSV and flag the unreliable ones."
  - "Which orders are within 3 km of our stores? I have store coordinates."
---

# 地址解析

定位一句话：**先把地址洗干净、预演算清要请求几次，再用腾讯位置服务批量转坐标（或反查地址），每行都标清成功、低可信还是失败，最后才算距离。** key 只放环境变量，默认不联网。

## 何时使用

- 「这批收货地址帮我转成经纬度，要在地图上打点」
- 「门店坐标有了，哪些订单在 3 公里配送范围内？」
- 「一批经纬度想反查成地址」
- 「解析结果有的跑到别的城市了，怎么筛出来？」
- 「为什么我的点和地图上差了一截？」（坐标系问题）

不适用：
- 驾车或骑行路线、路网距离、送达时长 → 看腾讯位置服务官方文档的路线规划、距离矩阵相关章节；本技能只算直线（球面）距离，可作初筛。
- 画热力图、做地图可视化 → 本技能产出带坐标的 CSV，交给可视化工具或数据可视化类技能。
- 查某个人住在哪、定位他人 → 不做。

## 流程（5 步）

| 步 | 做什么 | 产出 |
|---|---|---|
| 1 清洗 | `clean` 子命令，核对 `geo_clean_note` 里每行做了什么 | cleaned.csv |
| 2 预演 | `geocode` 不加 `--run`：看去重后要请求几次，不联网、不需要 key | 屏幕预览 |
| 3 小批量 | `--run --limit 20`：看低可信、失败的比例和原因 | 试跑结果 |
| 4 全量 | `--run --cache 缓存文件`：中断或失败后重跑只补缺的 | geo.csv |
| 5 复核与距离 | 人工处理「低可信 / 失败」；`distance` 算最近门店与半径 | dist.csv |

### 地址清洗（摘要）

全角转半角；去掉「收货地址：」前缀；括号里是「近地铁、放门口」这类备注就删，是「XX大厦、XX小区」这类地标就去括号保留；删手机号和座机；去空格；地址开头缺省市时用该行城市列或 `--region` 补上；地址里写的城市和城市列矛盾时**不改写，只标出**；清洗后为空的行不请求。完整规则、判断依据、已知局限与人工修正办法见 [references/address-cleaning.md](references/address-cleaning.md)。

### 调用腾讯位置服务（通用形态，以腾讯位置服务官方文档为准）

- 地理编码：GET `https://apis.map.qq.com/ws/geocoder/v1/`，参数 `address=地址`、`key`。
- 逆地址解析：同一路径，参数 `location=纬度,经度`（纬度在前）、`key`。
- 脚本约定：返回 `status` 为 0 算成功，坐标取 `result.location` 的 `lat`/`lng`；可信度、精度、行政区划等字段名和含义以官方文档为准，返回里没有就不据此判断。
- key：在腾讯位置服务控制台申请并开启 WebService 能力，可能还要配置调用来源限制（如 IP 白名单），入口与选项以控制台为准。脚本**未实现签名校验**，开了签名的 key 需按官方「签名校验」章节自行补充。
- 配额与费用以控制台和官方说明为准。脚本用预演、去重、缓存、开头连续失败自动停止来省调用量。
- 官方文档去哪查：腾讯位置服务官网 → WebService API 的地理编码、逆地址解析、坐标转换、签名校验、状态码章节（章节名以官网为准）。更多细节见 [references/tencent-webservice-notes.md](references/tencent-webservice-notes.md)。

### 坐标系与距离

- WGS-84 是 GPS 设备用的坐标；GCJ-02 是国内地图服务普遍使用的加偏坐标，腾讯位置服务用的是它（以官方文档为准）；BD-09 是百度地图在 GCJ-02 上再加偏的坐标。**所有点必须同一坐标系才能打点、算距离**，GPS 采集的点先用官方坐标转换接口转换，本技能不提供自研转换公式。
- 距离用半正矢公式（haversine），地球平均半径 6371.0088 千米；球面模型和椭球真值的差别通常在 0.5% 以内，做配送范围初筛够用。直线距离不是路网距离，最终以实际路线或配送时长为准。

## 脚本

`scripts/geocode_batch.py`（纯标准库）四个子命令：`clean`、`geocode`、`reverse`、`distance`。默认预演；超时、最多 2 次重试、请求间隔、缓存续跑、Ctrl-C 保存已完成部分都已内置；输出 UTF-8 带 BOM 的 CSV，Excel 可直接打开，输入的 GBK CSV 也能读。

```bash
# 1–2 清洗与预演（不联网）
python3 scripts/geocode_batch.py clean orders.csv --column 地址 --city-column 城市 --out cleaned.csv
python3 scripts/geocode_batch.py geocode orders.csv --column 地址 --city-column 城市 --out geo.csv
# 3–4 真正请求：key 只放环境变量，不要写进脚本、贴进对话或提交进仓库
export TENCENT_MAP_KEY=你的key
python3 scripts/geocode_batch.py geocode orders.csv --column 地址 --city-column 城市 --out geo.csv --run --limit 20 --cache geo-cache.json
# 5 最近门店与配送半径（默认读 geo_lat / geo_lng 两列）
python3 scripts/geocode_batch.py distance geo.csv --stores stores.csv --radius-km 3 --out dist.csv
# 离线演练：本地假服务，不连任何外部接口（假服务另开一个终端运行，Ctrl-C 停止）
python3 scripts/mock_geocoder.py --port 8765
python3 scripts/geocode_batch.py geocode orders.csv --column 地址 --out geo.csv --run --base-url http://127.0.0.1:8765
```

输出列：`geo_clean_address`、`geo_clean_note`、`geo_lat`、`geo_lng`、`geo_coord_sys`、`geo_province`、`geo_city`、`geo_district`、`geo_reliability`、`geo_level`、`geo_status`（成功 / 低可信 / 失败 / 未请求 / 未处理）、`geo_note`。标「低可信」的四种情况：可信度低于 `--min-reliability`（默认 7，阈值含义以官方文档为准）；结果城市与城市列不一致；3 个以上不同地址落在同一点；坐标不在中国大致范围内。

## 信息不全或出错时

| 情况 | 怎么处理 | 对用户说的话（模板） |
|---|---|---|
| 缺关键信息 | 只问 3 个：地址在哪列、有没有城市列；正向还是反查；用途是打点还是配送范围（后者要门店坐标）。其余用默认值（阈值 7、间隔 0.5 秒），交付物里标 [待确认] | 「先告诉我：地址在哪一列、有没有城市列、结果拿来打点还是算配送范围？其余按默认跑，标 [待确认] 的你再定。」 |
| 输入矛盾（地址写杭州、城市列写深圳） | 不擅自改写，脚本已标出；给两种理解让用户选 | 「A004 地址是杭州、城市列是深圳：是城市列填错了，还是这单确实发往杭州？」 |
| 经纬度写反或不是数字 | 脚本标「疑似经纬度写反」「不是数字」且不请求；给调换列的办法 | 「这 3 行纬度超出 -90～90，像是经纬度写反了，把两列互换后再跑这几行。」 |
| 超出范围（路网距离、路线规划、查人住址） | 前两者指向官方路线规划、距离矩阵文档；查人住址直接拒绝 | 「直线距离我能算；骑行距离要用路线规划类接口，看官方文档对应章节。」 |
| 时间紧，只要最小可用版 | 降级为：`clean` + 预演 + `--limit 50` 小批量；只交 `geo_lat`、`geo_lng`、`geo_status` 三列和失败清单 | 「先跑前 50 行给你看效果和失败原因，全量等你确认后再跑。」 |
| 坚持越界（要把 key 发给我代跑、要多 key 轮换绕配额、要爬地图数据） | 不接收 key，不绕配额，不爬取；给本机执行的命令 | 「key 请留在你电脑的环境变量里，命令我写好，你本地执行，结果贴回来我帮你看。」 |

脚本退出码：

| 退出码 / 报错 | 原因 | 修正办法 |
|---|---|---|
| 0 | 完成；个别行失败写在 `geo_status`、`geo_note` | 按复核清单处理 |
| 1 | 参数或配置错：列名不存在（报错会列出现有列）、没读到 key 环境变量、输出文件已存在、非本机地址却用 http | 按报错改；覆盖输出加 `--overwrite` |
| 2 | 文件读不了、编码认不出、写不进去 | 检查路径；CSV 另存为 UTF-8 |
| 3 | 请求全部失败，或开头连续 3 次同样错误已自动停止 | 看「失败原因」汇总，查 key、调用来源限制、配额、网络 |
| 130 | 按了 Ctrl-C | 已完成的行已写出；带同一个 `--cache` 重跑 |

## 输出契约

交付物按固定顺序：
1. **处理摘要**：总行数、实际请求次数、成功 / 低可信 / 失败 / 未请求各多少。
2. **结果文件**：文件名与关键列含义，注明坐标系 GCJ-02（以官方文档为准）。
3. **人工复核清单**：按原因分组（城市不一致、地址太笼统、查不到、超时、空地址），每组给行号和处理动作。
4. **距离结论**（如有）：半径内外各多少、每家门店覆盖多少、其中低可信多少；注明「直线距离，不是路网距离」。
5. **提醒**：配额费用以官方为准；key 只放环境变量。

占位符：用户没给的写 [待补]（门店坐标、配送半径）；默认值与推测写 [待确认]（可信度阈值、城市补全）。

交付前自检（逐条是/否）：
- [ ] 真正请求之前做过预演，并告诉了用户请求次数？
- [ ] 每一行都有 `geo_status`，失败和低可信都写了原因？
- [ ] 所有参与距离计算的点是同一坐标系？
- [ ] 距离结论写明了是直线距离，并单列了低可信行？
- [ ] 正文、命令和输出里都没有真实 key？

## 示例

**用户（示例）**：订单表里的收货地址转成经纬度，再看哪些单在两家店 5 公里内。

**助手先问**：地址和城市在哪两列？门店坐标从哪个地图取的？key 是否已开 WebService 能力（只放你本机环境变量，别发给我）？

**用户**：「地址」「城市」两列；门店坐标取自腾讯地图；key 有了。

**交付物（节选，完整过程与真实输出见 [examples/batch-geocode-run.md](examples/batch-geocode-run.md)）**：

```
【处理摘要】13 行｜实际请求 11 次｜成功 6｜低可信 4｜失败 2｜未请求 1
【需要人工复核】城市不一致 1 行（A004）｜地址太笼统 3 行（A005–A007）｜查不到 1 行（A008）｜超时 1 行（A011，带缓存重跑）｜空地址 1 行（A009）
【距离结论】5 千米内 9 单，全部最近福田店，其中 3 单坐标低可信，不能据此承诺配送；直线距离，不是路网距离
```

## 常见问题（FAQ）

- **为什么好几个地址落在同一个点？** 地址太笼统（只到区或片区），被解析到区县或城市中心。补门牌或小区名后重跑这几行。
- **可信度阈值设多少合适？** 默认 7，含义以官方文档对该字段的说明为准。打点展示可以放宽，配送判定要从严，并人工抽查。
- **能把 key 给你，直接帮我跑吗？** 不接收 key。命令写好由你本地执行，把摘要或失败清单贴回来，我帮你分析。
- **和别的地图对不上？** 多半是坐标系不同。不同地图服务可能使用不同坐标系，混用前先按各自官方文档统一。
- **直线距离能当配送距离吗？** 只能初筛。河流、高架、单行道会让实际路程远大于直线距离，最终以路线规划结果或实际配送时长为准。
- **一次能跑多少条、要花多少钱？** 以腾讯位置服务控制台和官方说明为准。脚本会先告诉你去重后的请求次数，用 `--limit` 小批量试。
- **中途断了要从头来吗？** 不用。带上同一个 `--cache` 重跑，成功过的地址不会再请求。

## 常见错误（反模式）

- 不清洗直接请求 → 备注、电话、缺省市让可信度大面积偏低，还白花调用量 → 先 `clean` 和预演。
- 只保留经纬度两列 → 无法知道哪些点不可靠 → 保留 `geo_status`、`geo_note`，交付复核清单。
- GPS 坐标和地图坐标混着算 → 距离和打点都偏 → 统一到同一坐标系再算。
- 把直线距离当配送距离承诺给顾客 → 超区投诉 → 直线只作初筛，边界订单用路网复核。
- key 写进脚本、前端或仓库 → 泄露后被盗用 → 只放环境变量，控制台限制调用来源，泄露立即重建。
- 失败后整批重跑 → 重复消耗调用量 → 用 `--cache` 只补失败的。
- 忽略「多个地址落在同一点」 → 一批订单被当成在区中心，距离全错 → 回原始数据补全地址。

## 边界与不做什么

- 不代为申请、接收或保存 key，不在对话里替用户调用接口；脚本在用户本机运行。
- 接口路径、参数、返回字段、状态码、配额与价格只写通用形态，以腾讯位置服务官方文档和控制台为准。
- 不提供坐标系转换的自研公式或纠偏算法。
- 不做针对个人的定位或住址查询，不爬取地图或兴趣点数据，不用多 key 轮换等方式绕开配额。
- 收货地址属于个人信息：只在本地处理，只保留需要的列，结果不外传；无关的姓名、电话列可先删掉再处理。