唐诗宋词元曲查询：国学/教育类 App 集成方案，一键查诗人自动生成赏析
# 唐诗宋词元曲查询：国学/教育类 App 集成方案，一键查诗人自动生成赏析
> 接口：唐诗宋词元曲等诗词查询（apiCode=1620）· 免费 · 请求方式 POST/GET · 返回 JSON · 适用：教育机构、国学/语文类 App 团队 · 阅读约 7 分钟
## 核心要点
- 教育场景的核心是「诗人详情 + 诗词赏析」组合：1620-4 取 `biography`（生平），1620-5 取 `contentlist`（原文/译文/注释）
- 可按 `note` 标签（如「高中文言文」）在本地做学段筛选，接口本身不支持按标签检索
- 组合调用需做好异常兜底：查不到、限流、空结果都要有友好提示（详见缓存与限流篇）
## Why：教育产品最需要的就是「即查即学」
语文/国学类 App、课堂大屏、背诵打卡小程序，都需要随时调出一首诗的全套资料：作者谁、什么朝代、原文怎么读、白话怎么译、难点怎么注。ShowAPI 这套接口把数据准备好了，你要做的是把它们组合成一个「赏析页」，并处理好边界情况，让学生用得顺。
## What：方案涉及的接口
| 能力 | 接入点 | 关键出参 |
|------|--------|---------|
| 朝代导航 | 1620-3 | `dynastyId` / `dynasty` |
| 诗人详情 | 1620-4 | `biography`（生平）、`poetId` |
| 诗词赏析 | 1620-5 | `contentlist`（原文/译文/注释）、`note`（标签） |
| 计费 | 免费（有使用档次限制） | — |
## How：教育赏析页的组合调用
### 步骤 1 · 建「朝代 → 诗人」导航
用 1620-3 拉朝代，1620-4 按 `dynastyId` 拉诗人，缓存结果做左侧导航。
### 步骤 2 · 进入诗人页，展示小传 + 作品列表
1620-4 返回 `biography`，直接渲染诗人小传；同时用 `poetId` 调 1620-5 拉作品列表（翻页见分页篇）。
### 步骤 3 · 进入诗词页，渲染赏析
1620-5 的 `contentlist` 提供原文/译文/注释，`note` 提供标签（如「高中文言文」）。
**Python（组合调用示意）**
```python
import requests
APP_KEY = "YOUR_APPKEY"
H = {"content-type": "application/x-www-form-urlencoded"}
def call(path, **params):
r = requests.post(f"https://route.showapi.com/{path}",
params={"appKey": APP_KEY, **params}, headers=H, timeout=10)
body = r.json().get("showapi_res_body", {})
if body.get("ret_code") != "0":
raise RuntimeError(body.get("remark"))
return body
# 诗人小传
poet = call("1620-4", poet="苏轼")["poetInfo"][0]
print("小传:", poet["biography"][:40], "...")
# 该诗人作品 + 标签
poems = call("1620-5", poetId=poet["poetId"], page=1)["poemInfo"]
for p in poems:
tags = [t for t in p.get("note", "").split("，") if t]
print(p["title"], "标签:", tags)
```
**cURL（诗人小传）**
```bash
curl -X POST "https://route.showapi.com/1620-4?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "poet=%E8%8B%8F%E8%BD%BC&page=1"
```
**Node.js（fetch，拉作品）**
```javascript
const APP_KEY = "YOUR_APPKEY";
const H = { "content-type": "application/x-www-form-urlencoded" };
const body = (await (await fetch(`https://route.showapi.com/1620-5?appKey=${APP_KEY}`, {
method: "POST", headers: H,
body: new URLSearchParams({ poetId: "5b1e3644cbf69480cb8e81b7", page: 1 }),
})).json()).showapi_res_body;
body.poemInfo.forEach(p => console.log(p.title, "→", p.note));
```
## 返回示例与解析
1620-4 诗人小传片段：
```json
{
"showapi_res_body": {
"ret_code": "0",
"poetInfo": [
{ "poet": "苏轼", "dynasty": "宋代", "poetId": "5b1e3644cbf69480cb8e81b7",
"biography": "苏轼（1037－1101），北宋文学家、书画家、美食家……" }
]
}
}
```
1620-5 的 `note` 示例：`辞赋精选，高中文言文，古文观止，写景，饮酒，感叹，哲理`——逗号分隔，可在本地拆成标签做学段筛选。
## 进阶 / 边界
- **标签本地筛选**：`note` 不能作为查询参数，需拉取后在本地按逗号拆分、按「高中文言文」等关键词过滤。
- **异常兜底**：`biography` 可能较长，做截断+展开；`contentlist` 可能为空，提示「暂无注释」而非报错。
- **限流与缓存**：教育类 App 访问集中，务必缓存朝代/诗人/热门诗词（见限流缓存篇），避免触发免费档位限制。
- **内容校对**：译文/注释为辅助材料，正式教学发布前建议由专业老师核对。
## FAQ
**Q1：能不能直接按「高中文言文」检索诗词？**
不能。`note` 是返回字段不是查询参数。做法是拉取诗人全部作品（翻页），在本地按 `note` 关键词筛选。
**Q2：一个诗人作品太多，App 卡顿怎么办？**
用分页（每页 20 条）做无限滚动，配合缓存；首屏只加载第一页，用户下滑再加载下一页。
**Q3：biography 太长，详情页放不下？**
可只显示前若干字 + 「展开全文」，或把完整小传放到独立诗人详情页。
**Q4：免费档位够教育类 App 用吗？**
取决于日活与缓存命中率。热点诗人/诗词缓存后真实调用很低；上线前建议小流量探明档位上限，再定缓存策略。
## 相关能力 / 下一步阅读
- [唐诗宋词元曲查询：搭一个带原文/译文/注释的古诗文学习卡片](https://www.showapi.com/guides/poem-learning-card-1620) — 单首赏析卡片实现
- [唐诗宋词元曲查询：免费也有档次限制，如何用本地缓存避免触发限流？](https://www.showapi.com/guides/poem-rate-limit-cache-1620) — 教育高并发下的缓存
- **本系列共 12 篇**：查看[唐诗宋词元曲查询指南总目录](https://www.showapi.com/guides/poem-guides-1620)
