古籍查询 API 在教育 / 国学场景的集成实践：读书笔记与知识库
# 古籍查询 API 在教育 / 国学场景的集成实践：读书笔记与知识库
> 接口：古籍查询（apiCode 1643）· **免费服务** · 提供原文 / 译文 / 注释结构化数据
> 适用人群：国学教育产品、读书笔记工具、儿童/学生诵读类应用团队 · 阅读时间：约 6 分钟
## 核心要点
- 古籍查询返回的是结构化篇章数据（`original` 原文、`trainslation` 译文、`annotation` 注释、`section` 篇章名），天然适合做"对照阅读"与"知识库检索"。
- 典型链路：用 1643-2 拿目录（或直接用[总目录](https://www.showapi.com/guides/ancient-books-catalog-1643)的 titleId）→ 用 1643-3 按 titleId 翻页抓全某部书 → 落库 → 前端做对照展示 / 检索。
- 可结合已有的"成语/古文学习卡片"思路，把单篇内容做成带译文、可背诵、可测验的卡片。
## Why：这能解决什么？
国学/语文类产品常需要"原文+译文对照""按书名/篇章检索""给孩子做诵读卡片"。手工录入古籍既慢又易错，而这个免费接口直接给出可机读的内容。把它作为内容源，可以省掉大量录入成本，把精力放在产品体验上。
## What：最小可用架构
```
[ShowAPI 1643]
│ (1643-2 拿目录 / 总目录定位 titleId)
▼
[抓取层] 1643-3 按 titleId 翻页 → 全篇章 original/trainslation/annotation
│
▼
[存储层] 关系表：books / chapters（含 titleId、section、原文、译文、注释）
│
▼
[应用层] 对照阅读、检索、诵读卡片、笔记标注
```
### 推荐数据表（MySQL 示意）
```sql
CREATE TABLE books (
id BIGINT PRIMARY KEY,
title VARCHAR(128),
title_id VARCHAR(64) UNIQUE, -- 来自 1643-2 / 总目录
author VARCHAR(64)
);
CREATE TABLE chapters (
id BIGINT PRIMARY KEY,
book_title_id VARCHAR(64),
section VARCHAR(128), -- 篇章名，如"学而篇"
original TEXT, -- 原文（按段落用 \n 拼接）
translation TEXT, -- 译文（trainslation，字段名少 s）
annotation TEXT, -- 注释（可能为空）
note TEXT, -- 参考资料
seq INT -- 篇章顺序
);
```
## How：抓取并落库（Python 示例）
```python
import requests, time
APPKEY = "YOUR_APPKEY"
BASE = f"https://route.showapi.com/1643-3?appKey={APPKEY}"
HEADERS = {"content-type": "application/x-www-form-urlencoded"}
def fetch_book(title_id):
chapters, page = [], 1
while True:
body = requests.post(BASE, data={"titleId": title_id, "page": str(page)},
headers=HEADERS, timeout=10).json()["showapi_res_body"]
if body.get("ret_code") != "0":
raise RuntimeError(body.get("remark"))
for ch in body["ancientBooksInfo"]:
chapters.append({
"section": ch["section"],
"original": "\n".join(ch.get("original", [])),
"translation": "\n".join(ch.get("trainslation", [])), # 键名 trainslation
"annotation": "\n".join(ch.get("annotation", []) or []),
"note": ch.get("note", ""),
})
if body["currentPage"] >= body["allPages"]:
break
page += 1
time.sleep(0.2) # 控制节奏，避免触发免费接口档次限制
return chapters
# 例：抓取《论语》（titleId 见总目录）
lunyu = fetch_book("5b23316f618cd77360b91f0d")
print("论语篇章数:", len(lunyu))
```
> 落库时把 `original`/`translation` 按段落用换行拼接即可；展示时再按 `\n` 拆分还原段落。注释可能为空，存库前判空处理。
## 进阶 / 边界
- **诵读卡片**：把单条 `chapter` 做成卡片（正面原文、背面译文），已契合用户既有"成语/古文学习卡片"工作流，可直接复用卡片生成与展示逻辑。
- **检索式知识库**：对 `original`/`translation` 建全文索引，支持"按句子搜出处""按主题聚合"，比纯目录更有价值。
- **注释数据稀疏**：`annotation` 常为空，产品设计上不要把"注释"作为必展示项，缺失时优雅降级（只显示原文+译文）。
- **免费接口限流**：批量抓取多部书时注意节奏与档次限制（见[常见问题与避坑](https://www.showapi.com/guides/ancient-books-faq-1643)），必要时分时段抓取并本地缓存。
## FAQ
**Q1：能做带译文的对照阅读 App 吗？**
A：可以。1643-3 同时返回 `original` 与 `trainslation`，按段落配对展示即可实现对照阅读。
**Q2：注释老是空，影响大吗？**
A：多数篇章注释为空属正常数据情况，不影响原文/译文主体；产品上做缺失降级即可。
**Q3：批量抓取很多部书会被限流吗？**
A：免费接口设使用档次限制，建议控制并发、加间隔并本地缓存已抓内容。
## 相关能力 / 下一步阅读
- [古籍查询 API：可查询的 218 部古籍总目录（含 titleId）](https://www.showapi.com/guides/ancient-books-catalog-1643)
- [古籍查询 API 分页机制：page / maxResult / allPages 怎么用](https://www.showapi.com/guides/ancient-books-pagination-1643)
- [古籍查询 API 常见问题与避坑指南（trainslation 拼写、注释为空、分页）](https://www.showapi.com/guides/ancient-books-faq-1643)
- **本系列共 10 篇**：查看[古籍查询 API 指南总目录](https://www.showapi.com/guides/ancient-books-guides-1643)
