汉字多功能转换器：地址分词实战（物流/地图场景的地址智能切分）
汉字多功能转换器汉字转拼音简繁转换全角半角地址分词 # 汉字多功能转换器：地址分词实战（物流/地图场景的地址智能切分）
> 接口/接入点：汉字多功能转换器 · 地址分词（99-117） · 是否免费：是 · 请求方式：POST/GET · 返回格式：JSON · 适用人群：物流、地图、数据分析工程师 · 阅读时间：约 7 分钟
## 核心要点
- ⚠️ **地址分词与其它 5 个接入点不同**：请求参数叫 `addr`（**query 参数、必须**），不是 `content`。
- ⚠️ **返回结构也不同**：业务字段是 `ret_code`（number，0=成功）、`msg`（错误提示，无错时不存在）、`result`（分词结果），不是 `data`/`flag`。
- `addr` 字符长度**必须大于 4**，否则不返回结果。
## Why：为什么地址分词特殊
物流下单、地图标注、地址库清洗时，常需要把"云南省昆明市五华区学府路745号"切成"省/市/区/路/号"的结构化片段。地址分词接入点专为这类中文地址文本设计，但它的调用方式与返回字段都和"转拼音/简繁/全半角"不一样——本文专门讲清这些差异，避免你拿错字段。
## What：接口速览
| 项 | 说明 |
|----|------|
| 地址 | `https://route.showapi.com/99-117?appKey=YOUR_APPKEY` |
| 请求方式 | POST 或 GET |
| 必填参数 | `addr`（**query 参数**：`?addr=地址文本`），长度必须 > 4 |
| 返回（业务） | `ret_code`（number）、`msg`（String，无错时不存在）、`result`（String） |
> 注意：这里 `addr` 是**查询参数**，与其它接入点把 `content` 放在表单体（form body）的写法不一致，调用时务必区分。
## How：调用地址分词
**Python（requests，addr 放 params）**
```python
import requests
url = "https://route.showapi.com/99-117"
params = {"appKey": "YOUR_APPKEY", "addr": "云南省昆明市五华区学府路745号"}
r = requests.get(url, params=params, timeout=10).json()
if r.get("showapi_res_code") == 0:
body = r["showapi_res_body"]
if body.get("ret_code") == 0:
print("分词:", body["result"]) # 云南省 昆明市 五华区 学府路 745号
else:
print("业务失败:", body.get("msg"))
else:
print("系统失败:", r.get("showapi_res_error"))
```
**cURL**
```bash
curl "https://route.showapi.com/99-117?appKey=YOUR_APPKEY&addr=%E4%BA%91%E5%8D%97%E7%9C%81%E6%98%86%E6%98%8E%E5%B8%82%E4%BA%94%E5%8D%8E%E5%8C%BA%E5%AD%A6%E5%BA%9C%E8%B7%AF745%E5%8F%B7"
```
**Node.js（fetch）**
```javascript
const url = "https://route.showapi.com/99-117?appKey=YOUR_APPKEY&addr=" +
encodeURIComponent("云南省昆明市五华区学府路745号");
const r = await fetch(url).then(x => x.json());
const b = r.showapi_res_body;
if (b.ret_code === 0) console.log(b.result);
else console.log("失败:", b.msg);
```
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "c1a2...",
"showapi_res_body": {
"ret_code": 0,
"result": "云南省 昆明市 五华区 学府路 745号",
"msg": ""
}
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_code` | int | 系统状态码，0 成功（先判断它） |
| `showapi_res_body.ret_code` | number | 业务状态码，0 表示分词成功 |
| `showapi_res_body.result` | String | 分词结果，仅在 `ret_code=0` 时返回 |
| `showapi_res_body.msg` | String | 错误提示，**无错误时该字段不存在** |
## 进阶/边界
- **`addr` 长度必须 > 4**：过短地址（如"北京"）可能不返回结果或报错，调用前先做长度校验。
- 这是**业务级 `ret_code`**（number），与系统级 `showapi_res_code`（int）是两个字段，判断顺序：先看 `showapi_res_code`，再看 `ret_code`。
- 不要拿本文的 `result`/`ret_code`/`msg` 去套其它接入点的 `data`/`flag`，反之亦然。
## FAQ
**Q1：为什么我用 content 传地址没返回？**
地址分词只认 `addr` 参数（query），不认 `content`；请改用 `?addr=...`。
**Q2：返回里没有 data/flag？**
正常。地址分词返回 `ret_code`/`msg`/`result`，与其它接入点结构不同。
**Q3：报错了但没有 msg？**
`msg` 仅在出错时存在；无错时该字段不出现，判断用 `if ("msg" in body)`。
**Q4：短地址（如"北京"）没结果？**
`addr` 长度需大于 4；建议传入更完整的地址文本。
## 相关能力 / 下一步阅读
- [汉字多功能转换器返回字段全解：data / simpleData / flag 与系统级 showapi_res_code](https://www.showapi.com/guides/hanzi-converter-response-fields-99)
- [汉字多功能转换器错误排查：showapi_res_code 与地址分词的 ret_code/msg](https://www.showapi.com/guides/hanzi-converter-errors-99)
- [物流/地图行业方案：用地址分词统一清洗全国收货地址](https://www.showapi.com/guides/hanzi-converter-logistics-plan-99)
- **本系列共 12 篇**：查看[汉字多功能转换器指南总目录](https://www.showapi.com/guides/hanzi-converter-guides-99)
