古籍查询 API：5 分钟快速开始（获取古籍目录与明细）
# 古籍查询 API：5 分钟快速开始（获取古籍目录与明细）
> 接口：古籍查询（apiCode 1643）· 接入点 1643-2 / 1643-3 · **免费服务** · 请求方式 POST/GET · 返回 JSON
> 适用人群：新注册用户、初级开发者、国学爱好者 · 阅读时间：约 5 分钟
## 核心要点
- 古籍查询有两个接入点：1643-2 返回「可查询古籍目录」（含 titleId），1643-3 按 titleId 返回某部书的原文/译文/注释。
- 标准用法是「先查目录拿 titleId → 再查明细」，两步都只需一个 AppKey。
- 返回里**译文的键名是 `trainslation`**（拼写为 trainslation，少一个 s），不是 translation——这是最容易踩的坑。
## Why：这跟我有什么关系？
如果你在做国学类 App、读书笔记工具、儿童/学生诵读卡片，或者只是想随手查一段古文和它的现代汉语译文，这个免费接口能直接给你结构化的原文+译文，省去自己录入和校对的功夫。两步调用、零费用，适合快速验证想法。
## What：前置条件与接口速览
| 项目 | 说明 |
|------|------|
| 接口名称 | 古籍查询（apiCode 1643） |
| 接入点 1 | 查询古籍名称 `https://route.showapi.com/1643-2?appKey=YOUR_APPKEY` |
| 接入点 2 | 查询古籍明细 `https://route.showapi.com/1643-3?appKey=YOUR_APPKEY` |
| 鉴权 | query 参数 `appKey`（从 ShowAPI 控制台获取） |
| 计费 | 免费服务，注册后默认可免费调用（设使用档次限制） |
| 返回 | JSON，业务数据在 `showapi_res_body` 内 |
前置条件：① 注册并登录 ShowAPI；② 在控制台拿到 AppKey；③ 确认已开通古籍查询（免费接口默认可用）。
## How：5 步跑通
**步骤 1 — 获取 AppKey**
登录后到 [AppKey 管理页](https://www.showapi.com/console#/myApp) 复制你的 AppKey，下面代码里替换 `YOUR_APPKEY`。
**步骤 2 — 调 1643-2 拿古籍目录（含 titleId）**
Python（requests）：
```python
import requests
APPKEY = "YOUR_APPKEY"
url = f"https://route.showapi.com/1643-2?appKey={APPKEY}"
r = requests.post(url, 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')}")
titles = body["titles"] # 列表，每项是 {"title": "论语", "titleId": "5b23316f618cd77360b91f0d"}
print("可查询古籍数量:", len(titles))
print("示例:", titles[0]) # {'title': '论语', 'titleId': '5b23316f618cd77360b91f0d'}
```
cURL：
```bash
curl -X POST "https://route.showapi.com/1643-2?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded"
```
Node.js（fetch）：
```javascript
const APPKEY = "YOUR_APPKEY";
const res = await fetch(`https://route.showapi.com/1643-2?appKey=${APPKEY}`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" }
});
const body = (await res.json()).showapi_res_body;
if (body.ret_code !== "0") throw new Error("查询失败: " + body.remark);
console.log("可查询古籍数量:", body.titles.length);
console.log("示例:", body.titles[0]);
```
**步骤 3 — 取一个 titleId**
从步骤 2 的 `titles` 里挑一部书，复制它的 `titleId`（例如《论语》的 `5b23316f618cd77360b91f0d`）。
**步骤 4 — 调 1643-3 拿明细**
Python（requests）：
```python
import requests
APPKEY = "YOUR_APPKEY"
TITLE_ID = "5b23316f618cd77360b91f0d" # 《论语》的 titleId
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')}")
for item in body["ancientBooksInfo"]:
print("篇章:", item["section"])
print("原文:", item["original"][0])
print("译文:", item["trainslation"][0]) # 注意键名是 trainslation
```
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 item of body.ancientBooksInfo) {
console.log("篇章:", item.section);
console.log("原文:", item.original[0]);
console.log("译文:", item.trainslation[0]); // 键名 trainslation
}
```
**步骤 5 — 解析返回**
`ancientBooksInfo` 是数组，每个元素是一部书的一个「篇章」：`section` 是篇章名（如"学而篇"），`original`/`trainslation`/`annotation` 都是字符串数组（按段落切分），`note` 是参考资料说明。
## 返回示例（1643-3，节选）
```json
{
"showapi_res_code": 0,
"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
}
}
```
## 进阶 / 边界
- **译文键名坑**：JSON 里译文的字段是 `trainslation`（少一个 s）。OpenAPI 文档也未列此字段，按真实返回为准。
- **注释可能为空**：`annotation` 经常是 `[]`，不代表接口出错，只是该篇章没有注释数据。
- **1643-2 返回的是完整目录**：实测一次返回 218 部古籍；目前文档未提供"按书名过滤"的参数，拿到 titleId 后请走 1643-3 取明细。
- **分页**：1643-3 用 `page` 翻页，默认每页 20 条，`allPages` 是总页数。
## FAQ
**Q1：ret_code 不是 0 怎么办？**
A：看 `remark` 字段的提示，通常是 AppKey 无效或未开通接口。确认 AppKey 正确且接口已开通（免费接口默认可用）。
**Q2：为什么取不到译文？**
A：检查你用的键名是不是 `translation`。真实键名是 `trainslation`（拼写少 s）。详见[古籍查询 API 返回字段全解](https://www.showapi.com/guides/ancient-books-fields-1643)。
**Q3：1643-2 能不能按书名搜索？**
A：目前 OpenAPI 未暴露按书名过滤的参数，实测常见参数名也返回完整目录。建议先用 1643-2 拿全量目录，再按 titleId 走 1643-3。
**Q4：免费接口的调用有限制吗？**
A：免费服务注册后默认可调用，设有使用档次限制（防滥用），具体档位以官方[免费 API 说明](https://www.showapi.com/free-api)为准。
## 相关能力 / 下一步阅读
- [古籍查询 API：两个接入点怎么选？（名称目录 vs 明细）](https://www.showapi.com/guides/ancient-books-points-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)
- **本系列共 10 篇**：查看[古籍查询 API 指南总目录](https://www.showapi.com/guides/ancient-books-guides-1643)
