成语词典三大接入点怎么选：搜索 / 详情 / 随机一篇说清
# 成语词典三大接入点怎么选：搜索 / 详情 / 随机一篇说清
> 接口：成语词典（apiCode=2964） · 接入点：2964-1 / 2964-2 / 2964-3 · 是否免费：是 · 请求方式：POST/GET · 返回格式：JSON · 适用人群：选型阶段的开发者、产品经理 · 阅读时间：约 5 分钟
## 核心要点
- 三个接入点职责不同：搜索（找哪些）、详情（看一条全貌）、随机（来一条碰运气）。
- **最大坑**：搜索只返回成语名和 id，**没有解释**；解释在详情接入点。
- 选型看目的：列出候选 → 2964-1；展示某条释义 → 2964-2；趣味/每日一句 → 2964-3。
## Why：为什么选型很重要
成语词典不是「一个接口返回所有东西」。如果你以为调一次搜索就能拿到拼音、解释、出处，会卡在「怎么只有名字」。先弄清三个接入点各自给什么，能避免返工和错误的架构假设。
## What：三接入点速览
| 接入点 | 名称 | 入参 | 出参 | 典型用途 |
|--------|------|------|------|---------|
| 2964-1 | 搜索成语 | `keyword`(必填)、`page`(选填) | 分页成语名列表(`id`+`word`) | 输入联想、查词列表、候选 |
| 2964-2 | 成语详情 | `id` 或 `word`(二选一) | 单条完整释义 | 点开某条看拼音/解释/出处/示例 |
| 2964-3 | 随机成语 | 无 | 单条完整释义 | 每日一成语、抽卡、小游戏 |
请求地址分别为 `https://route.showapi.com/2964-1`、`2964-2`、`2964-3`，均带 `appKey`。
## How：选型决策
### 场景 A：用户输入片段，想看有哪些成语
用 **2964-1 搜索成语**，`keyword` 传片段（支持部分匹配）。
```python
import requests
APPKEY = "YOUR_APPKEY"
r = requests.get("https://route.showapi.com/2964-1",
params={"appKey": APPKEY, "keyword": "画", "page": "1"}, timeout=10)
body = r.json()["showapi_res_body"]
print([it["word"] for it in body["list"]]) # ['画蛇添足', '画龙点睛', ...]
```
### 场景 B：用户点开某条，要看解释
用 **2964-2 成语详情**，传搜索拿到的 `id`（更精确，避免同名歧义）。
```python
import requests
APPKEY = "YOUR_APPKEY"
r = requests.post("https://route.showapi.com/2964-2",
data={"appKey": APPKEY, "id": "b83eace0-ca55-4b0e-b85a-670d5604e1fc"}, timeout=10)
body = r.json()["showapi_res_body"]
print(body["word"], body["pinyin"], body["explain"])
```
### 场景 C：想随机来一条做每日打卡
用 **2964-3 随机成语**，无需任何参数。
```python
import requests
APPKEY = "YOUR_APPKEY"
r = requests.post("https://route.showapi.com/2964-3", data={"appKey": APPKEY}, timeout=10)
body = r.json()["showapi_res_body"]
print(body["word"], body["explain"])
```
## 进阶 / 边界
- 搜索的 `list` 每项只有 `id`/`word`，要释义必须再调详情——这是主链路，见[两步流](https://www.showapi.com/guides/idiom-search-detail-flow-2964)。
- 详情的 `id` 与 `word` 二选一；推荐用 `id`（搜索结果已带），避免同名成语歧义，详见[详情参数篇](https://www.showapi.com/guides/idiom-detail-id-or-word-2964)。
- 随机成语每次结果不同，不适合「精确复现某条」，需要确定结果请用搜索+详情。
## FAQ
**Q：能不能一次搜索就拿到所有解释？**
不能。搜索接口设计为只返回列表（id+word），解释在详情接入点，需二次调用。
**Q：三个接入点都要单独开通吗？**
接口级（apiCode=2964）开通即可，三个接入点同属一个接口，MCP/OpenAPI 也覆盖全部。
**Q：随机成语能指定分类或字数吗？**
按文档，2964-3 无参数，不支持按字数/分类筛选。需要筛选请用搜索+关键词。
**Q：详情用 id 好还是 word 好？**
优先 `id`：搜索结果已提供且唯一，能避开同名歧义；`word` 适合你只持有成语名时。详见[参数篇](https://www.showapi.com/guides/idiom-detail-id-or-word-2964)。
## 相关能力 / 下一步阅读
- [成语词典：5 分钟接入，从注册到第一条搜索结果](https://www.showapi.com/guides/idiom-dictionary-quickstart-2964)
- [成语词典：从搜索到释义的两步流，搭建查词功能](https://www.showapi.com/guides/idiom-search-detail-flow-2964)
- [随机成语能怎么玩？每日一成语 / 打卡 / 小游戏集成](https://www.showapi.com/guides/idiom-random-usage-2964)
- **本系列共 15 篇**：查看[成语词典（apiCode=2964）官方指南总目录](https://www.showapi.com/guides/idiom-dictionary-guides-2964)
