成语详情：用 id 还是 word 查询？参数用法与避坑
# 成语详情：用 id 还是 word 查询？参数用法与避坑
> 接口：成语词典（apiCode=2964） · 接入点：成语详情(2964-2) · 是否免费：是 · 请求方式：POST/GET · 返回格式：JSON · 适用人群：开发者 · 阅读时间：约 4 分钟
## 核心要点
- 成语详情（2964-2）接受 `id` 或 `word`，**二选一**即可查到释义。
- 推荐用 `id`：搜索结果已带 `id`，唯一且能避开同名成语歧义。
- 仅当你只持有成语名（无 id）时，才用 `word` 查询。
## Why：id 和 word 到底差在哪
详情接口给你两种查法，但二者可靠性不同。同名成语在汉语里存在（如不同出处的同形成语），用 `word` 可能命中非你预期的那条；用 `id` 则精确定位搜索结果里的那一条。本文说清二选一的最佳实践。
## What：参数速览
| 参数 | 必填 | 说明 |
|------|------|------|
| `id` | 否（与 word 二选一） | 成语唯一 id，来自搜索结果 `list[].id` |
| `word` | 否（与 id 二选一） | 成语名 |
> 官方 OpenAPI 中 `id`/`word` 均**未标 required**，逻辑上至少传其一；两者都不传时返回取决于服务实现，实战需处理空结果。
## How：两种写法
### 用 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)
b = r.json()["showapi_res_body"]
print(b["word"], b["explain"])
```
### 用 word（仅持名字时）
```python
import requests
APPKEY = "YOUR_APPKEY"
r = requests.post("https://route.showapi.com/2964-2",
data={"appKey": APPKEY, "word": "守株待兔"}, timeout=10)
b = r.json()["showapi_res_body"]
print(b["explain"])
```
```bash
curl -X POST "https://route.showapi.com/2964-2?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "word=守株待兔"
```
## 返回示例与解析
```json
{
"showapi_res_body": {
"ret_code": 0, "remark": "查询成功！",
"word": "守株待兔", "pinyin": "shǒu zhū dài tù",
"explain": "比喻死守经验，不知变通。",
"derivation": "《韩非子·五蠹》", "sample": "凡事须主动，不可守株待兔。"
}
}
```
## 进阶 / 边界
- **同名歧义**：当存在同名成语，`word` 查询可能返回非预期条；`id` 来自搜索结果、唯一确定，优先用 `id`。
- **都不传**：文档未定义空参行为，建议你的代码在调用前校验「id 或 word 至少一个非空」，并对 `ret_code != 0` 做好降级。
- **两步流衔接**：搜索拿到 id → 详情用 id 是最稳链路，详见[两步流](https://www.showapi.com/guides/idiom-search-detail-flow-2964)。
## FAQ
**Q：id 和 word 必须同时传吗？**
不需要，二选一。推荐只传 id。
**Q：用 word 查会出错吗？**
语法上不会，但当存在同名成语时可能命中非预期条，故优先 id。
**Q：id 从哪里来？**
来自搜索接口（2964-1）返回的 `list[].id`。
**Q：两个都不传会怎样？**
文档未定义，建议前端先校验再发请求，避免拿到空/异常结果。
## 相关能力 / 下一步阅读
- [成语词典：从搜索到释义的两步流，搭建查词功能](https://www.showapi.com/guides/idiom-search-detail-flow-2964)
- [成语详情字段详解：拼音 / 解释 / 出处 / 示例如何呈现给用户](https://www.showapi.com/guides/idiom-detail-fields-2964)
- [成语词典三大接入点怎么选：搜索 / 详情 / 随机一篇说清](https://www.showapi.com/guides/idiom-dictionary-access-points-2964)
- **本系列共 15 篇**：查看[成语词典（apiCode=2964）官方指南总目录](https://www.showapi.com/guides/idiom-dictionary-guides-2964)
