字典查询：拼音查字与部首查字（1524-3/1524-4）两种检索路径怎么选
# 字典查询：拼音查字与部首查字（1524-3/1524-4）两种检索路径怎么选
> 元信息：接口 **字典查询** 接入点 **1524-3 拼音查字 / 1524-4 部首查字** · 免费服务 · POST/GET · JSON · 适用：检索类功能开发者、教育产品 · 阅读时间约 6 分钟
## 核心要点
- 1524-3 拼音查字：必填 `pinyin`（如「a」），返回该拼音下的汉字列表（含 `hanzi`/`bihua`/`py_tone`/`pinyin`）。
- 1524-4 部首查字：必填 `bushou`（如「力」），返回该部首下的汉字列表（含 `hanzi`/`bushou`/`bihua`/`pinyin`）。
- 两者都返回 `datas` 数组；选哪个取决于你的用户「知道拼音」还是「知道部首」。
## Why：两种检索路径解决不同入口
用户查字有两种常见起点：知道读音（拼音）但不知怎么写，或看到字形（部首）但不确定读音。1524-3 和 1524-4 分别覆盖这两条路径，组合使用即可搭建完整的「拼音检索 + 部首检索」双入口。
## What：前置条件与接口速览
| 项 | 1524-3 拼音查字 | 1524-4 部首查字 |
|----|----|----|
| 请求地址 | `…/1524-3?appKey=YOUR_APPKEY` | `…/1524-4?appKey=YOUR_APPKEY` |
| 必填参数 | `pinyin`（拼音，如 `a`） | `bushou`（部首，如 `力`） |
| 返回结构 | `datas[]` | `datas[]` |
| 典型字段 | `hanzi`, `bihua`, `py_tone`, `pinyin` | `hanzi`, `bushou`, `bihua`, `pinyin` |
| 计费 | 免费（档位限额） | 免费（档位限额） |
接口详情页：[1524-3](https://www.showapi.com/apiGateway/view/1524/3) · [1524-4](https://www.showapi.com/apiGateway/view/1524/4)
## How：快速接入
### 步骤 1：拼音查字（Python）
```python
import requests
APP_KEY = "YOUR_APPKEY"
resp = requests.post(
"https://route.showapi.com/1524-3",
params={"appKey": APP_KEY},
data={"pinyin": "a"},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10,
)
res_body = resp.json().get("showapi_res_body", {})
if res_body.get("ret_code") != "0":
raise RuntimeError(res_body.get("remark"))
for item in res_body.get("datas", []):
print(item.get("hanzi"), item.get("pinyin"), item.get("py_tone"), item.get("bihua"))
```
### 步骤 2：部首查字（Python）
```python
resp = requests.post(
"https://route.showapi.com/1524-4",
params={"appKey": APP_KEY},
data={"bushou": "力"},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10,
)
res_body = resp.json().get("showapi_res_body", {})
if res_body.get("ret_code") != "0":
raise RuntimeError(res_body.get("remark"))
for item in res_body.get("datas", []):
print(item.get("hanzi"), item.get("bushou"), item.get("bihua"), item.get("pinyin"))
```
### 步骤 3：cURL / Node.js
```bash
curl -X POST "https://route.showapi.com/1524-3?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" -d "pinyin=a"
```
```javascript
const r = await (await fetch(`https://route.showapi.com/1524-4?appKey=YOUR_APPKEY`, {
method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ bushou: "力" }),
})).json();
console.log(r.showapi_res_body.datas);
```
## 返回示例与字段解析
**1524-3 拼音查字**
```json
{ "showapi_res_body": { "ret_code":"0",
"datas": [ {"hanzi":"吖","bihua":"6","py_tone":"ā","pinyin":"a"},
{"hanzi":"厑","bihua":"7","py_tone":"未分类","pinyin":"a"} ] } }
```
**1524-4 部首查字**
```json
{ "showapi_res_body": { "ret_code":"0",
"datas": [ {"hanzi":"力","bushou":"力","bihua":"2","pinyin":"lì"},
{"hanzi":"勸","bushou":"力","bihua":"19","pinyin":"quàn"} ] } }
```
| 字段 | 说明 |
|------|------|
| `hanzi` | 汉字 |
| `bihua` | 笔画数（字符串） |
| `py_tone` | 带声调拼音（1524-3 专有，可能「未分类」） |
| `pinyin` | 拼音 |
| `bushou` | 部首（1524-4 返回，便于回显） |
## 进阶 / 边界
- **`py_tone` 可能「未分类」**：1524-3 中部分字 `py_tone` 为「未分类」，展示时回退到 `pinyin`。
- **结果集可能很大**：常用拼音/部首下汉字很多，前端务必分页或做首屏截断（如前 50 个），不要一次性渲染全部。
- **先查列表再查详情**：拼音/部首查字返回的是「字列表」，若要单字完整释义，拿 `hanzi` 去调 1524-5 汉字详情。
- **组合检索**：可同时提供两种入口，用户选其一，列表项点击后跳到 1524-5 详情。
## FAQ
**Q1：pinyin 参数要带声调吗？**
示例用无声调的「a」。建议按文档示例传无声调拼音；若带声调返回不符预期，回退到无声调形式。
**Q2：bushou 部首参数怎么传？**
直接传部首汉字本身（如「力」「水」），用 URL 编码即可（cURL 的 `-d` 与表单会自动编码）。
**Q3：拼音查字返回的 py_tone 是空的怎么办？**
部分字 `py_tone` 为「未分类」，属正常数据，展示时用 `pinyin` 兜底即可。
**Q4：这两个接口和汉字详情（1524-5）怎么配合？**
1524-3/1524-4 返回候选汉字列表，点击某字后用其 `hanzi` 调 1524-5 拿完整释义，形成「检索 → 详情」闭环。
## 相关能力 / 下一步阅读
- [字典查询：汉字详细信息（1524-5）接入](https://www.showapi.com/guides/dict-char-detail-1524)
- [字典查询：返回字段全解，ret_code 与 showapi_res_body 一文读懂](https://www.showapi.com/guides/dict-response-codes-1524)
- [字典查询：语文学习 App 如何集成？](https://www.showapi.com/guides/dict-learning-app-1524)
- **本系列共 12 篇**：查看[字典查询指南总目录](https://www.showapi.com/guides/dict-guides-1524)
