# 成语词典：5 分钟接入，从注册到第一条搜索结果
> 接口：成语词典（apiCode=2964） · 接入点：搜索成语(2964-1) · 是否免费：是 · 请求方式：POST/GET · 返回格式：JSON · 适用人群：新注册用户、初级开发者 · 阅读时间：约 5 分钟
## 核心要点
- 成语词典是**免费**接口，控制台拿到 AppKey 即可调用，无需购买资源包。
- 搜索成语（2964-1）只需一个必填参数 `keyword`，返回分页的成语名列表。
- 注意：搜索只返回成语名与 `id`，**完整释义在「成语详情」接入点**——本篇先跑通搜索。
## Why：这跟我有什么关系
如果你在做教育类小程序、语文学习工具、内容创作插件，或者只是想在自家产品里加一个「查成语」的能力，成语词典能让你不维护成语库、不写爬虫，几分钟就拿到结构化数据。免费 + 标准 JSON 返回，接入成本极低。
## What：前置条件与接口速览
| 项目 | 说明 |
|------|------|
| 接口/接入点 | 成语词典 → 搜索成语（2964-1） |
| 请求地址 | `https://route.showapi.com/2964-1` |
| 请求方式 | POST 或 GET |
| 鉴权 | query 参数 `appKey`（来自控制台） |
| 计费 | 免费服务 |
| 必填参数 | `keyword`（String，搜索关键字） |
| 选填参数 | `page`（String，查询页码，默认 1） |
| 返回格式 | JSON，业务数据在 `showapi_res_body` |
前置条件：① 注册 ShowAPI 账号；② 在控制台「我的应用」创建应用拿到 `appKey`；③ 已开通成语词典（免费接口，通常默认可用）。
## How：第一次调用
### 步骤 1：拿到 AppKey
登录后进入 [AppKey 管理](https://www.showapi.com/console#/myApp)，复制任意一个应用的 `appKey`。
### 步骤 2：发起搜索请求（Python）
```python
import requests
APPKEY = "YOUR_APPKEY"
url = "https://route.showapi.com/2964-1"
params = {"appKey": APPKEY, "keyword": "守株待兔", "page": "1"}
try:
r = requests.get(url, params=params, timeout=10)
r.raise_for_status()
data = r.json()
except requests.RequestException as e:
print("请求失败:", e)
raise
body = data.get("showapi_res_body", {})
if body.get("ret_code") != 0:
print("业务失败:", body.get("remark"))
else:
print("总数:", body.get("allNum"), "当前页:", body.get("currentPage"))
for item in body.get("list", []):
print(item["word"], item["id"])
```
### 步骤 3：用 cURL 验证
```bash
curl -X POST "https://route.showapi.com/2964-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "keyword=守株待兔&page=1"
```
### 步骤 4：用 Node.js(fetch) 验证
```javascript
const APPKEY = "YOUR_APPKEY";
const params = new URLSearchParams({ appKey: APPKEY, keyword: "守株待兔", page: "1" });
fetch(`https://route.showapi.com/2964-1?${params}`, { method: "POST" })
.then(r => r.json())
.then(data => {
const body = data.showapi_res_body;
if (body.ret_code !== 0) { console.log("业务失败:", body.remark); return; }
body.list.forEach(it => console.log(it.word, it.id));
})
.catch(e => console.error("请求失败:", e));
```
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"ret_code": 0,
"remark": "查询成功！",
"list": [
{ "word": "守株待兔", "id": "b83eace0-ca55-4b0e-b85a-670d5604e1fc" }
],
"maxResult": 20,
"currentPage": 1,
"allNum": 1,
"allPages": 1
}
}
```
| 字段 | 含义 |
|------|------|
| `showapi_res_body.ret_code` | 0 为成功，其他为失败 |
| `list[].word` | 成语名 |
| `list[].id` | 成语唯一 id，用于调「成语详情」拿释义 |
| `allNum` / `allPages` | 命中总数 / 总页数，分页用 |
| `maxResult` | 当前页返回条数上限 |
## 进阶 / 边界
- 搜索结果**只有成语名和 id，没有解释**。要展示拼音/解释/出处/示例，用 `id` 调 [成语详情（2964-2）](https://www.showapi.com/guides/idiom-search-detail-flow-2964)。
- `keyword` 支持部分匹配（如「株」也能命中「守株待兔」），详见[关键词与分页技巧](https://www.showapi.com/guides/idiom-search-keyword-tips-2964)。
- 免费服务仍有调用频率约束，生产环境建议加缓存，见[分页缓存策略](https://www.showapi.com/guides/idiom-pagination-cache-2964)。
## FAQ
**Q：报「appKey 错误」或鉴权失败怎么办？**
检查 AppKey 是否复制完整、是否混用了不同环境的应用；确认该应用已开通成语词典（免费接口一般默认可用）。
**Q：为什么 list 里只有成语名没有解释？**
搜索接口设计如此，释义在「成语详情」接入点。用 `id` 再调一次即可，见[两步流](https://www.showapi.com/guides/idiom-search-detail-flow-2964)。
**Q：返回 allNum 为 0 是什么情况？**
没有匹配该 keyword 的成语，或 keyword 为空。先确认 keyword 拼写，详见[关键词技巧](https://www.showapi.com/guides/idiom-search-keyword-tips-2964)。
**Q：免费接口需要购买资源包吗？**
不需要。免费服务直接调用，控制台拿到 AppKey 即可，无按次扣费。
## 相关能力 / 下一步阅读
- [成语词典返回字段全解：showapi_res_body 与 ret_code 一文读懂](https://www.showapi.com/guides/idiom-dictionary-response-codes-2964)
- [成语词典：从搜索到释义的两步流，搭建查词功能](https://www.showapi.com/guides/idiom-search-detail-flow-2964)
- [成语搜索关键词怎么写才准？部分匹配 / 分页技巧](https://www.showapi.com/guides/idiom-search-keyword-tips-2964)
- **本系列共 15 篇**：查看[成语词典（apiCode=2964）官方指南总目录](https://www.showapi.com/guides/idiom-dictionary-guides-2964)
