唐诗宋词元曲查询返回结构全解：ret_code、dynastyInfo、poemInfo 一文读懂
唐诗宋词元曲查询返回字段ret_codedynastyInfopoemInfo # 唐诗宋词元曲查询返回结构全解：ret_code、dynastyInfo、poemInfo 一文读懂
> 接口：唐诗宋词元曲等诗词查询（apiCode=1620）· 免费 · 请求方式 POST/GET · 返回 JSON · 适用：已接入或准备接入的开发者 · 阅读约 6 分钟
## 核心要点
- 所有返回都包在 `showapi_res_body` 内，系统级字段（`showapi_res_code` 等）在它外层，业务字段在它里面
- `ret_code` 是**字符串** `"0"` 表示成功，判断务必用字符串比较
- 三个接入点的列表字段 `dynastyInfo` / `poetInfo` / `poemInfo` 以及诗词正文 `contentlist` **都是数组**，遍历时按数组处理
## Why：先把结构看明白，后面少踩坑
三个接入点字段不少，尤其容易在两点上栽跟头：一是把 `ret_code` 当数字比较导致判断失效；二是把本该是数组的 `poemInfo` / `contentlist` 当成单对象，结果取不到值。本篇把三个接入点的字段一次性摊开，配一张对照表，建议收藏当速查页用。
## What：统一封装规则与接口速览
| 项目 | 说明 |
|------|------|
| 接口编码 | 1620 |
| 接入点 | 1620-3 查询朝代列表 / 1620-4 人名或朝代查询诗人 / 1620-5 名称查询诗词列表 |
| 返回格式 | JSON |
| 外层结构 | `showapi_res_code` / `showapi_res_error` / `showapi_res_id` / `showapi_res_body` |
| 业务数据 | 全部位于 `showapi_res_body` 内 |
| 成功标识 | `showapi_res_body.ret_code == "0"`（字符串） |
## How：三接入点字段对照
### 接入点 1620-3 · 查询朝代列表
返回 `dynastyInfo`（Object[]），每项：
| 字段 | 类型 | 说明 |
|------|------|------|
| `dynasty` | String | 朝代名称（宋代、唐代、南北朝…） |
| `dynastyId` | String | 朝代唯一 ID，下游查诗人入参 |
> 文档示例共 15 个朝代：宋代、唐代、南北朝、元代、两汉、现代、清代、五代、明代、魏晋、金朝、隋代、先秦、近代、未知。
### 接入点 1620-4 · 人名或朝代查询诗人
入参（均选填）：`dynastyId`（朝代Id）、`poet`（诗人名，如「苏轼」）、`page`（页码，默认 1）。
返回：
| 字段 | 类型 | 说明 |
|------|------|------|
| `ret_code` | String | `"0"` 成功 |
| `remark` | String | 提示信息 |
| `allPages` | 数值 | 总页数 |
| `currentPage` | 数值 | 当前页 |
| `allNum` | 数值 | 总条数 |
| `maxResult` | 数值 | 每页条数（文档示例为 20） |
| `poetInfo` | Object[] | 诗人列表 |
| `poetInfo[].poet` | String | 诗人名 |
| `poetInfo[].dynastyId` | String | 朝代 ID |
| `poetInfo[].dynasty` | String | 朝代名 |
| `poetInfo[].poetId` | String | 诗人唯一 ID，下游查诗词入参 |
| `poetInfo[].biography` | String | 生平简介 |
### 接入点 1620-5 · 名称查询诗词列表
入参（均选填）：`poetId`（诗人id）、`title`（诗词名称，**不支持模糊查询**）、`page`（页码，默认 1）。
返回：
| 字段 | 类型 | 说明 |
|------|------|------|
| `poemInfo` | Object[] | 诗词列表 |
| `poemInfo[].title` | String | 诗名 |
| `poemInfo[].dynasty` / `dynastyId` | String | 朝代名 / 朝代 ID |
| `poemInfo[].poemId` | String | 诗唯一 ID |
| `poemInfo[].note` | String | 标签（如「辞赋精选，高中文言文，古文观止…」） |
| `poemInfo[].poetId` / `poet` | String | 诗人 ID / 诗人名 |
| `poemInfo[].contentlist` | Object[] | 原文/译文/注释，可多段 |
| `contentlist[].original` | String | 原文 |
| `contentlist[].translation` | String | 译文 |
| `contentlist[].annotation` | String | 注释 |
| `allPages` / `currentPage` / `allNum` / `maxResult` | 数值 | 分页信息 |
**通用判断模板（Python）**
```python
import requests
def call(url, app_key, **params):
r = requests.post(url, params={"appKey": app_key, **params},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10)
body = r.json().get("showapi_res_body", {})
if body.get("ret_code") != "0": # 注意是字符串比较
raise RuntimeError(body.get("remark"))
return body
# 三个接入点都是返回数组，统一遍历
body = call("https://route.showapi.com/1620-5", "YOUR_APPKEY", poet="苏轼", page=1)
for poem in body["poemInfo"]: # poemInfo 是数组
for seg in poem["contentlist"]: # contentlist 也是数组
print(seg["original"])
```
## 返回示例与解析
以 1620-5 查询苏轼《前赤壁赋》为例（节选）：
```json
{
"showapi_res_body": {
"ret_code": "0",
"remark": "查询成功！",
"poemInfo": [
{
"title": "前赤壁赋",
"dynasty": "宋代",
"dynastyId": "5b1de348cbf6a77b365977e5",
"poemId": "5b1e3749cbf69480cb8e81f4",
"note": "辞赋精选，高中文言文，古文观止，写景，饮酒，感叹，哲理",
"contentlist": [
{
"original": "壬(rén)戌(xū)之秋，七月既望……",
"translation": "壬戌年秋，七月十六日……",
"annotation": "壬戌：宋神宗元丰五年……"
}
],
"poetId": "5b1e3644cbf69480cb8e81f7",
"poet": "苏轼"
}
],
"maxResult": 20,
"allNum": 258,
"allPages": 13,
"currentPage": 1
}
}
```
## 进阶 / 边界
- **数组思维**：`dynastyInfo` / `poetInfo` / `poemInfo` / `contentlist` 全部是数组。即使只返回一条，也要用下标或 `for` 遍历，不要直接 `.field`。
- **`ret_code` 是字符串**：文档中所有状态码值都是字符串（如 `"0"`），用 `== "0"` 判断；若用 `== 0` 会恒为 False。
- **失败枚举未公开**：文档只说明「`ret_code` 非 0 为失败」，未列出具体失败码与含义。遇到非 0 时以 `remark` 文案为准，不要臆测具体错误码。
## FAQ
**Q1：ret_code 返回 0 但 showapi_res_body 里没数据？**
先确认入参是否命中数据。例如 1620-5 的 `title` 是精确匹配，写错一字或用了别称都会查不到；1620-4 若 `dynastyId` 与 `poet` 都不传，也可能无结果。先用已知示例值（如 `poet=苏轼`）验证链路。
**Q2：poemInfo 和 contentlist 到底几层？**
两层数组：`poemInfo` 是「诗列表」，每首诗里的 `contentlist` 是「段落列表」（一首长诗/辞赋可能分成多段，每段含原文/译文/注释）。渲染时两层都要遍历。
**Q3：maxResult 固定是 20 吗？能改吗？**
文档示例中 `maxResult` 为 20，是由服务端控制的每页条数，请求参数里没有「每页条数」字段，不能由调用方修改，只能靠 `page` 翻页。
**Q4：biography 和 note 字段一定会返回吗？**
二者均为字符串字段，查到对应数据时才会有内容；空数据时可能为空串或不出现，前端需做空值兜底。
## 相关能力 / 下一步阅读
- [唐诗宋词元曲查询：从「朝代」到「诗人」到「诗词」三步全链路串联](https://www.showapi.com/guides/poem-three-step-flow-1620) — 把三个接入点的字段串成一条链
- [唐诗宋词元曲查询：page 与 maxResult=20 分页翻页拉取全部诗词](https://www.showapi.com/guides/poem-pagination-1620) — 翻页拉全量数据
- **本系列共 12 篇**：查看[唐诗宋词元曲查询指南总目录](https://www.showapi.com/guides/poem-guides-1620)
