行政区划查询拼音字段能干嘛？pinYin / simplePy / prePinYin 在搜索排序中的应用
# 行政区划查询拼音字段能干嘛？pinYin / simplePy / prePinYin 在搜索排序中的应用
> 接口 / 接入点：行政区划查询（apiCode 1149）· 区域查询 1149-1 / 子区域查询 1149-2 · 免费服务
> 请求方式：POST / GET · 返回格式：JSON · 适用人群：前端 / 搜索功能开发者 · 阅读时间：约 6 分钟
## 核心要点
- 返回里带了三套拼音字段：`pinYin`（全拼）、`simplePy`（简拼）、`prePinYin`（首字母）。
- 它们让你无需额外拼音库，就能做「拼音 / 首字母检索」和「按拼音排序」。
- 字段为空时（如部分下级区域）需兜底，不要硬依赖。
## Why：拼音字段能省一个依赖
做地区选择 / 通讯录式 UI 时，用户常想输入「km」或「kunming」直接定位「昆明」。如果自己接拼音转换库，要处理多音字、生僻字，还占体积。行政区划查询直接把拼音随结果返回，拿来即用。
## What：三个拼音字段的区别
| 字段 | 含义 | 示例（昆明） |
|------|------|------|
| pinYin | 全拼（空格分隔） | kun ming shi |
| simplePy | 简拼（连写） | KM |
| prePinYin | 拼音首字母 | K |
> 子区域查询返回示例里 `pinYin` 为 `Liwan`、`simplePy` 为 `Lw`、`prePinYin` 为 `L`，可见字段命名一致。
## How：拼音检索 + 排序
### Python（按首字母检索 + 按全拼排序）
```python
import requests
def search_by_pinyin(keyword):
r = requests.get("https://route.showapi.com/1149-1",
params={"appKey": "YOUR_APPKEY", "areaName": keyword, "level": "2"},
timeout=10)
data = r.json()["showapi_res_body"]["data"]
# 首字母匹配
hit = [d for d in data if d.get("prePinYin", "").upper() == keyword.upper()]
# 按全拼排序
hit.sort(key=lambda d: d.get("pinYin", ""))
return hit
for item in search_by_pinyin("K"):
print(item["areaName"], item["pinYin"], item["simplePy"], item["prePinYin"])
```
### 前端（首字母分组列表）
```javascript
fetch(`https://route.showapi.com/1149-1?appKey=YOUR_APPKEY&areaName=云南&level=2`)
.then(r => r.json())
.then(d => d.showapi_res_body.data)
.then(list => {
const groups = {};
list.forEach(o => {
const k = (o.prePinYin || "#").toUpperCase();
(groups[k] = groups[k] || []).push(o.areaName);
});
console.log(groups); // { K: ["昆明市","曲靖市"], ... }
});
```
### cURL
```bash
curl -X POST "https://route.showapi.com/1149-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "level=2&areaName=%E4%BA%91%E5%8D%97&page=1"
```
## 返回示例
```json
{ "showapi_res_body": { "ret_code": 0, "data": [
{"areaName": "昆明市", "pinYin": "kun ming shi", "simplePy": "KM", "prePinYin": "K"},
{"areaName": "曲靖市", "pinYin": "qu jing shi", "simplePy": "QJ", "prePinYin": "Q"}
] } }
```
## 进阶 / 边界
- 拼音字段可能为空（尤其部分下级区域），检索 / 排序前要做空值兜底，避免 KeyError。
- `simplePy` 是连写简拼（如 `KM`），适合首字母快捷输入；`pinYin` 全拼适合模糊匹配。
- 多音字以官方数据为准，接口已处理好，无需你再判断。
## FAQ
**Q：三个拼音字段必须都存吗？**
按需求选：做首字母检索用 `prePinYin`，做全拼模糊用 `pinYin`，做简拼快捷用 `simplePy`。
**Q：拼音字段为空怎么办？**
部分下级区域可能为空，检索 / 排序时给个默认值（如 `#`）兜底，不要直接抛错。
**Q：prePinYin 是大写还是小写？**
返回示例为大写（如 `K`），比较时建议统一 `.upper()` 再比，避免大小写漏匹配。
**Q：能靠拼音反查 areaName 吗？**
可以拿拼音做匹配后取 `areaName`，但拼音可能重名，最终展示仍以 `areaName` / `wholeName` 为准。
## 相关能力 / 下一步阅读
- [行政区划查询返回字段全解：wholeName / 各级编码 / 拼音一文读懂](https://www.showapi.com/guides/region-query-response-fields-1149)
- [行政区划查询实战：省市区三级联动选择器前端实现](https://www.showapi.com/guides/region-query-cascade-1149)
- **本系列共 11 篇**：查看[行政区划查询指南总目录](https://www.showapi.com/guides/region-query-guides-1149)
