字典查询：5 分钟接入，从注册到查出第一个汉字详情
# 字典查询：5 分钟接入，从注册到查出第一个汉字详情
> 元信息：接口 **字典查询**（apiCode 1524）· 免费服务 · 请求方式 POST/GET · 返回 JSON · 适用：新注册用户、语文类 App 初级开发者 · 阅读时间约 5 分钟
## 核心要点
- 字典查询是**免费**接口，注册后默认即可调用，仅有档位限额（额度见官方档位说明），无需按次付费。
- 首次调用以「汉字详细信息（接入点 1524-5）」为例，只需一个必填参数 `hanzi`。
- 所有接入点统一通过 `https://route.showapi.com/1524-X?appKey=YOUR_APPKEY` 调用，返回包在 `showapi_res_body` 中。
## Why：为什么用字典查询接口
手写汉字字典既占体积又难维护多音字、部首、五笔、组词、释义。把查询交给接口，你的应用只需专注体验：学生查一个字，立刻拿到拼音、部首、笔画、五笔、组词与详细解释，无需自己维护词库。本文用最简单的「查一个汉字详情」带你跑通全流程。
## What：前置条件与接口速览
| 项 | 值 |
|----|----|
| 接口名称 | 字典查询 |
| apiCode | 1524 |
| 接入点（本次用） | 1524-5 汉字详细信息 |
| 请求地址 | `https://route.showapi.com/1524-5?appKey=YOUR_APPKEY` |
| 请求方式 | POST 或 GET |
| 鉴权 | URL 上的 `appKey`（在[控制台](https://www.showapi.com/console#/myApp)获取） |
| 计费 | 免费（有档位限额，详见 [免费档位说明](https://www.showapi.com/free-api)） |
| 返回格式 | JSON |
| 集成能力 | MCP、OpenAPI 3.0（YAML/JSON） |
接口详情页：[https://www.showapi.com/apiGateway/view/1524](https://www.showapi.com/apiGateway/view/1524)
## How：快速接入
### 步骤 1：获取 AppKey
登录 [ShowAPI 控制台](https://www.showapi.com/console#/myApp)，创建一个应用即可拿到 AppKey。把它替换到下面代码里的 `YOUR_APPKEY`。
### 步骤 2：调用（Python）
```python
import requests
APP_KEY = "YOUR_APPKEY"
URL = "https://route.showapi.com/1524-5"
resp = requests.post(
URL,
params={"appKey": APP_KEY},
data={"hanzi": "你"},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10,
)
resp.raise_for_status()
body = resp.json()
res_body = body.get("showapi_res_body", {})
if res_body.get("ret_code") != "0":
raise RuntimeError(f"查询失败：{res_body.get('remark')}")
# basic_explain / detail_explain 文档标为 String，但示例返回可能是数组，统一兼容
def to_text(v):
if isinstance(v, list):
return "\n".join(str(x) for x in v)
return str(v) if v is not None else ""
print("汉字：", res_body.get("hanzi"))
print("拼音：", res_body.get("pinyin"))
print("部首：", res_body.get("bushou"))
print("笔画：", res_body.get("bihua"))
print("五笔：", res_body.get("wubi"))
print("组词：", res_body.get("words"))
print("基本解释：", to_text(res_body.get("basic_explain")))
print("详细解释：", to_text(res_body.get("detail_explain")))
```
### 步骤 3：调用（cURL）
```bash
curl -X POST "https://route.showapi.com/1524-5?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "hanzi=%E4%BD%A0"
```
### 步骤 4：调用（Node.js）
```javascript
const APP_KEY = "YOUR_APPKEY";
const params = new URLSearchParams({ hanzi: "你" });
const resp = await fetch(`https://route.showapi.com/1524-5?appKey=${APP_KEY}`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: params,
});
const body = await resp.json();
const resBody = body.showapi_res_body;
if (resBody.ret_code !== "0") throw new Error("查询失败：" + resBody.remark);
const toText = (v) => (Array.isArray(v) ? v.join("\n") : (v == null ? "" : String(v)));
console.log("汉字：", resBody.hanzi, "拼音：", resBody.pinyin, "部首：", resBody.bushou);
console.log("基本解释：", toText(resBody.basic_explain));
```
## 返回示例与字段解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"ret_code": "0",
"remark": "查询成功！",
"words": "你娘 你老 你好 你儜 你那 你门",
"wubi": "wqiy",
"hanzi": "你",
"bushou": "亻",
"bihua": "7",
"pinyin": "nǐ",
"basic_explain": ["你nǐ", "ㄋㄧˇ", "称对方……", "英文翻译", "you"],
"detail_explain": ["你", "妳", "nǐ", "【代】", "……"]
}
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_body.ret_code` | String | "0" 成功，其他为失败 |
| `showapi_res_body.remark` | String | 提示信息，如「查询成功！」 |
| `hanzi` | String | 查询的汉字 |
| `pinyin` | String | 拼音（含声调） |
| `bushou` | String | 部首 |
| `bihua` | String | 笔画数 |
| `wubi` | String | 五笔编码 |
| `words` | String | 组词，空格分隔 |
| `basic_explain` | String / 数组 | 基本解释（注意可能返回数组，需兼容） |
| `detail_explain` | String / 数组 | 详细解释（可能返回数组，需兼容） |
## 进阶 / 边界
- **免费档位有限额**：高频调用可能触达档位上限，生产环境建议对静态字典数据做本地缓存（详见[字典查询（免费档位）：如何设计缓存与降级](https://www.showapi.com/guides/dict-cache-degrade-1524)）。
- **字段类型兼容**：`basic_explain`/`detail_explain` 文档标注为 String 但示例返回数组，解析时务必兼容两种形态，避免 `join` 报错。
- **其他接入点**：拼音查字（1524-3）、部首查字（1524-4）、词语成语解释（1524-6）各有自己的必填参数，详见[字典查询：返回字段全解](https://www.showapi.com/guides/dict-response-codes-1524)。
## FAQ
**Q1：接口真的是免费的吗？有隐藏费用吗？**
文档标注为「免费服务」，注册后默认可调用，仅设档位限额防滥用，无按次计费。具体额度见 [免费档位说明](https://www.showapi.com/free-api)。
**Q2：返回里有两个 code（showapi_res_code 和 ret_code），看哪个？**
系统级 `showapi_res_code` 标识 HTTP/网关层成功与否；业务结果看 `showapi_res_body.ret_code`，"0" 表示业务成功。判断业务是否成功用 `ret_code == "0"`。
**Q3：ret_code 返回非 0 怎么办？**
文档只说明 "0" 为成功、其他为失败，未枚举具体非 0 错误码。非 0 时读取 `remark` 字段获取提示信息，按提示检查 AppKey 与必填参数。
**Q4：汉字详情接口必须传哪些参数？**
仅一个必填参数 `hanzi`（要查询的汉字）。其余接入点（如拼音查字需 `pinyin`、词语解释需 `ciyu`）各有自己的必填项。
## 相关能力 / 下一步阅读
- [字典查询：返回字段全解，ret_code 与 showapi_res_body 一文读懂](https://www.showapi.com/guides/dict-response-codes-1524)
- [字典查询：汉字详细信息（1524-5）接入](https://www.showapi.com/guides/dict-char-detail-1524)
- [字典查询：语文学习 App 如何集成？](https://www.showapi.com/guides/dict-learning-app-1524)
- **本系列共 12 篇**：查看[字典查询指南总目录](https://www.showapi.com/guides/dict-guides-1524)
