古籍查询 API：按 titleId 获取古籍明细（原文 / 译文 / 注释）
# 古籍查询 API：按 titleId 获取古籍明细（原文 / 译文 / 注释）
> 接口：古籍查询（apiCode 1643）· 接入点 1643-3「查询古籍明细」· **免费服务** · 请求方式 POST/GET · 返回 JSON
> 适用人群：已拿到 titleId、要取古籍正文的开发者 · 阅读时间：约 5 分钟
## 核心要点
- 1643-3 的必填参数是 `titleId`（来自 1643-2 或[总目录](https://www.showapi.com/guides/ancient-books-catalog-1643)），选填 `page` 翻页。
- 返回 `ancientBooksInfo[]`，每个元素是一部书的一个「篇章」：`section`(篇章名)、`original`(原文)、`trainslation`(译文)、`annotation`(注释)。
- **译文的 JSON 键名是 `trainslation`（少一个 s）**，不是 translation；`annotation` 经常为空数组，不是出错。
## Why：什么时候用这一篇？
你已经知道要查哪部书（有了 titleId），现在要的是这部书的具体内容——原文对照译文，或者做带注释的展示。这篇教你怎么稳定地把内容取出来并正确解析。
## What：接口速览
| 项目 | 说明 |
|------|------|
| 接入点 | 查询古籍明细 `https://route.showapi.com/1643-3?appKey=YOUR_APPKEY` |
| 必填参数 | `titleId`（String，古籍 Id） |
| 选填参数 | `page`（String，查询页面，默认第 1 页，每页 20 条） |
| 关键返回 | `ancientBooksInfo[]`：`title`/`titleId`/`section`/`author`/`original`/`trainslation`/`annotation`/`note`/`ancientBookId` |
## How：按 titleId 取明细
以《论语》为例，titleId = `5b23316f618cd77360b91f0d`。
Python（requests）：
```python
import requests
APPKEY = "YOUR_APPKEY"
TITLE_ID = "5b23316f618cd77360b91f0d" # 《论语》
url = f"https://route.showapi.com/1643-3?appKey={APPKEY}"
r = requests.post(url,
data={"titleId": TITLE_ID, "page": "1"},
headers={"content-type": "application/x-www-form-urlencoded"}, timeout=10)
body = r.json()["showapi_res_body"]
if body.get("ret_code") != "0":
raise RuntimeError(f"查询失败: {body.get('remark')}")
print("书名:", body["ancientBooksInfo"][0]["title"], "| 作者:", body["ancientBooksInfo"][0]["author"])
print("总篇章数 allNum:", body["allNum"], "| 总页数 allPages:", body["allPages"])
for ch in body["ancientBooksInfo"]:
print("\n【" + ch["section"] + "】")
for o, t in zip(ch["original"], ch["trainslation"]):
print("原文:", o)
print("译文:", t)
if ch["annotation"]:
print("注释:", ch["annotation"])
```
cURL：
```bash
curl -X POST "https://route.showapi.com/1643-3?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "titleId=5b23316f618cd77360b91f0d&page=1"
```
Node.js（fetch）：
```javascript
const APPKEY = "YOUR_APPKEY";
const TITLE_ID = "5b23316f618cd77360b91f0d";
const res = await fetch(`https://route.showapi.com/1643-3?appKey=${APPKEY}`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ titleId: TITLE_ID, page: "1" })
});
const body = (await res.json()).showapi_res_body;
if (body.ret_code !== "0") throw new Error("查询失败: " + body.remark);
for (const ch of body.ancientBooksInfo) {
console.log("\n【" + ch.section + "】");
ch.original.forEach((o, i) => {
console.log("原文:", o);
console.log("译文:", ch.trainslation[i]);
});
}
```
## 返回示例与字段说明
```json
{
"showapi_res_body": {
"ret_code": "0",
"remark": "查询成功！",
"ancientBooksInfo": [
{
"title": "论语",
"titleId": "5b23316f618cd77360b91f0d",
"section": "学而篇",
"author": "佚名",
"original": ["子曰：“学而时习之，不亦说乎？……”"],
"trainslation": ["孔子说：“学了又时常温习和练习，不是很愉快吗？……”"],
"annotation": [],
"note": "参考资料： 1、 佚名.论语百科.http://lunyu.baike.com/article-29298.html",
"ancientBookId": "5b286b7e618c454cc40b5997"
}
],
"maxResult": 20,
"allNum": 20,
"allPages": 1,
"currentPage": 1
}
}
```
| 字段 | 含义 |
|------|------|
| `section` | 篇章名，如"学而篇""为政篇" |
| `original` | 原文，字符串数组（按段落切分） |
| `trainslation` | 译文，字符串数组（**键名拼写少 s**） |
| `annotation` | 注释，字符串数组，常为空 `[]` |
| `note` | 参考资料说明（来源链接等） |
| `ancientBookId` | 该篇章的内部 Id |
## 进阶 / 边界
- **译文逐段对齐**：`original[i]` 与 `trainslation[i]` 按段落一一对应，展示时按索引配对即可。
- **注释为空是正常的**：很多篇章 `annotation` 是 `[]`，不要据此判断调用失败（以 `ret_code` 为准）。
- **多页内容**：一部书可能跨多页，用 `page=2`、`page=3`… 翻页，直到 `currentPage == allPages`。翻页写法见[分页机制](https://www.showapi.com/guides/ancient-books-pagination-1643)。
- **字段细节**：完整字段含义与 `trainslation` 拼写坑，见[返回字段全解](https://www.showapi.com/guides/ancient-books-fields-1643)。
## FAQ
**Q1：返回里没有 translation，只有 trainslation？**
A：对，真实键名就是 `trainslation`（少一个 s）。这是接口返回的字段名，照此解析即可。
**Q2：annotation 是空数组，是不是接口坏了？**
A：不是。`annotation` 字段常为空，属正常数据缺失，以 `ret_code == "0"` 判断成功即可。
**Q3：titleId 从哪里来？**
A：来自 1643-2 的 `titles`，或见[218 部古籍总目录](https://www.showapi.com/guides/ancient-books-catalog-1643)。
## 相关能力 / 下一步阅读
- [古籍查询 API 返回字段全解：trainslation 拼写坑与每个字段含义](https://www.showapi.com/guides/ancient-books-fields-1643)
- [古籍查询 API 分页机制：page / maxResult / allPages 怎么用](https://www.showapi.com/guides/ancient-books-pagination-1643)
- [古籍查询 API：两个接入点怎么选？（名称目录 vs 明细）](https://www.showapi.com/guides/ancient-books-points-1643)
- **本系列共 10 篇**：查看[古籍查询 API 指南总目录](https://www.showapi.com/guides/ancient-books-guides-1643)
