古籍查询 API：两个接入点怎么选？（名称目录 vs 明细）
# 古籍查询 API：两个接入点怎么选？（名称目录 vs 明细）
> 接口：古籍查询（apiCode 1643）· 接入点 1643-2 / 1643-3 · **免费服务** · 请求方式 POST/GET · 返回 JSON
> 适用人群：准备集成的开发者、产品设计 · 阅读时间：约 4 分钟
## 核心要点
- 1643-2「查询古籍名称」返回**可查询古籍目录**（实测 218 部，每部含 `titleId`）——它告诉你"有哪些书、各自的 ID 是什么"。
- 1643-3「查询古籍明细」按 `titleId` 返回某部书某一篇章的**原文、译文、注释**——它给你"这本书具体写了什么"。
- 标准调用顺序是「先 1643-2 拿 titleId → 再 1643-3 取明细」，两个接入点用同一个 AppKey。
## Why：为什么要先分清这两个？
很多开发者第一次看到"查询古籍名称"会以为它是"按书名搜索"。实测下来，1643-2 返回的是完整目录（不是过滤搜索），真正拿内容要靠 1643-3 并传入它给的 `titleId`。把这两个接入点的职责搞清楚，能少走很多弯路。
## What：两接入点速览
| 接入点 | 地址 | 入参 | 出参（核心） | 作用 |
|------|------|------|------|------|
| 查询古籍名称（1643-2） | `…/1643-2` | 无必填（文档/OpenAPI 未暴露请求体参数） | `showapi_res_body.titles`: `[{title, titleId}]` | 拿可查询古籍目录 + 每部书的 ID |
| 查询古籍明细（1643-3） | `…/1643-3` | `titleId`（必填）、`page`（选填） | `ancientBooksInfo[]`: 原文/译文/注释等 | 按 ID 取某部书某篇章内容 |
## How：调用顺序
```
[1643-2 查询古籍名称] ──返回 218 部 {title, titleId}──▶ 你挑一部，取它的 titleId
│
▼
[1643-3 查询古籍明细] ──传入 titleId（+page）──▶ 返回该部书的篇章原文/译文/注释
```
Python 串起来：
```python
import requests
APPKEY = "YOUR_APPKEY"
# 1) 拿目录
catalog = requests.post(
f"https://route.showapi.com/1643-2?appKey={APPKEY}",
headers={"content-type": "application/x-www-form-urlencoded"}, timeout=10
).json()["showapi_res_body"]
if catalog.get("ret_code") != "0":
raise RuntimeError(catalog.get("remark"))
# 2) 选一部书（这里以《论语》为例，实际可从 catalog["titles"] 里匹配）
title_id = next(t["titleId"] for t in catalog["titles"] if t["title"] == "论语")
# 3) 查明细
detail = requests.post(
f"https://route.showapi.com/1643-3?appKey={APPKEY}",
data={"titleId": title_id, "page": "1"},
headers={"content-type": "application/x-www-form-urlencoded"}, timeout=10
).json()["showapi_res_body"]
if detail.get("ret_code") != "0":
raise RuntimeError(detail.get("remark"))
for ch in detail["ancientBooksInfo"]:
print(ch["section"], "→", ch["original"][0], "|", ch["trainslation"][0])
```
cURL（分两步，先拿 ID 再查明细）：
```bash
# 第一步：拿目录（从返回的 titles 里取想要的 titleId）
curl -X POST "https://route.showapi.com/1643-2?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded"
# 第二步：用 titleId 查明细
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 catalog = (await (await fetch(`https://route.showapi.com/1643-2?appKey=${APPKEY}`, {
method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }
})).json()).showapi_res_body;
if (catalog.ret_code !== "0") throw new Error(catalog.remark);
const titleId = catalog.titles.find(t => t.title === "论语").titleId;
const detail = (await (await fetch(`https://route.showapi.com/1643-3?appKey=${APPKEY}`, {
method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ titleId, page: "1" })
})).json()).showapi_res_body;
if (detail.ret_code !== "0") throw new Error(detail.remark);
for (const ch of detail.ancientBooksInfo) {
console.log(ch.section, "→", ch.original[0], "|", ch.trainslation[0]);
}
```
## 返回示例（1643-2 目录，节选）
```json
{
"showapi_res_body": {
"ret_code": "0",
"remark": "查询成功！",
"titles": [
{ "title": "论语", "titleId": "5b23316f618cd77360b91f0d" },
{ "title": "三十六计", "titleId": "5b2338d0618c1926d7fd47bd" }
]
}
}
```
## 进阶 / 边界
- **1643-2 不是书名搜索**：实测 `name=`/`title=`/`keyword=` 等常见参数都返回完整目录，未观察到过滤。文档/OpenAPI 也未暴露过滤参数。把它当"目录接口"用最稳。
- **titleId 是稳定的**：同一部书的 titleId 固定，可缓存下来反复用于 1643-3，省去每次先查目录。
- **一个 titleId 对应多篇章**：1643-3 返回的是「篇章数组」，用 `page` 翻页（见[分页机制](https://www.showapi.com/guides/ancient-books-pagination-1643)）。
## FAQ
**Q1：能不能只用一个接口就拿到原文？**
A：不能。明细必须传入 1643-2 给的 titleId，所以至少两步（或你提前缓存好 titleId）。
**Q2：我已经有想要的书的 titleId，还要调 1643-2 吗？**
A：不用，直接拿 titleId 调 1643-3 即可。[218 部古籍总目录](https://www.showapi.com/guides/ancient-books-catalog-1643)里已列出所有 titleId。
**Q3：两个接入点计费一样吗？**
A：都是免费服务，注册后默认可调用，设使用档次限制；每次调用 `showapi_fee_num` 计 1 次。
## 相关能力 / 下一步阅读
- [古籍查询 API：可查询的 218 部古籍总目录（含 titleId）](https://www.showapi.com/guides/ancient-books-catalog-1643)
- [古籍查询 API：按 titleId 获取古籍明细（原文 / 译文 / 注释）](https://www.showapi.com/guides/ancient-books-detail-1643)
- [古籍查询 API 返回字段全解：trainslation 拼写坑与每个字段含义](https://www.showapi.com/guides/ancient-books-fields-1643)
- **本系列共 10 篇**：查看[古籍查询 API 指南总目录](https://www.showapi.com/guides/ancient-books-guides-1643)
