古籍查询 API 常见问题与避坑指南（trainslation 拼写、注释为空、分页）
# 古籍查询 API 常见问题与避坑指南（trainslation 拼写、注释为空、分页）
> 接口：古籍查询（apiCode 1643）· **免费服务** · 接入点 1643-2 / 1643-3
> 适用人群：已接入或准备接入、遇到具体问题的开发者 · 阅读时间：约 5 分钟
## 核心要点
- 高频坑有三：① 译文字段叫 `trainslation`（少一个 s），不是 `translation`；② `annotation`（注释）常为空数组，不是出错；③ 1643-2 返回的是完整目录（实测 218 部），当前不按书名过滤。
- 翻页看 `allPages`/`currentPage`，`page` 从 1 开始。
- 免费接口有使用档次限制，批量抓取注意节奏与本地缓存。
## FAQ
**Q1：为什么 `data.translation` 取不到译文？**
A：真实键名是 **`trainslation`**（拼写少一个 s）。接口实际返回和官方 OpenAPI schema 都未用 `translation`。解析时改成 `data.trainslation`。详见[返回字段全解](https://www.showapi.com/guides/ancient-books-fields-1643)。
**Q2：返回的 `annotation` 是空数组 `[]`，是接口坏了吗？**
A：不是。`annotation`（注释）字段经常为空，属正常数据缺失。判断是否成功请一律以 `ret_code == "0"` 为准，不要看注释是否为空。
**Q3：1643-2「查询古籍名称」为什么返回全部书，不像按书名搜索？**
A：目前 OpenAPI 未暴露按书名过滤的参数，实测 `name=`/`title=`/`keyword=` 等常见参数都返回完整目录（实测 218 部）。把它当"目录接口"用最稳：先拿全量目录（或直接用[总目录](https://www.showapi.com/guides/ancient-books-catalog-1643)），定位到 `titleId` 再走 1643-3 查明细。
**Q4：`page` 从 0 还是 1 开始？怎么知道翻完了？**
A：`page` 从 **1** 开始；不传默认第 1 页。判断是否翻完，比较返回的 `currentPage` 与 `allPages`，相等即最后一页。分页循环写法见[分页机制](https://www.showapi.com/guides/ancient-books-pagination-1643)。
**Q5：免费接口调用有限制吗？批量抓取要注意什么？**
A：免费服务注册后默认可调用，但设使用档次限制（防滥用），具体档位以官方[免费 API 说明](https://www.showapi.com/free-api)为准。批量抓取多部书时建议：控制并发、请求间加小间隔、抓全后本地缓存，避免触发限流。每次调用 `showapi_fee_num` 计 1 次。
**Q6：ret_code 不是 0 怎么办？**
A：先看 `remark` 的提示。常见原因：AppKey 无效或未开通接口。确认 AppKey 正确、接口已开通（免费接口默认可用）后再试。
**Q7：titleId 会变吗？可以缓存吗？**
A：`titleId` 由接口方给定，实测稳定，可缓存复用，省去每次先查目录。如某次调用拿到的不一致，以实时返回为准。
**Q8：MCP / OpenAPI 里字段和真实返回对不上？**
A：以接口实测返回为最终依据。已知差异是官方 OpenAPI 未列 `trainslation` 字段，但接口实际返回包含它。MCP 接入见[通过 MCP 调用](https://www.showapi.com/guides/ancient-books-mcp-1643)，文档导入见[OpenAPI 导入](https://www.showapi.com/guides/ancient-books-openapi-1643)。
## 避坑速查表
| 现象 | 真实原因 | 正确处理 |
|------|---------|----------|
| `translation` 取不到 | 键名是 `trainslation` | 改用 `trainslation` |
| `annotation` 为空 | 数据缺失，非错误 | 以 `ret_code` 判断成功，缺省降级 |
| 1643-2 返回全部书 | 当前不按书名过滤 | 用总目录定位 titleId 再查明细 |
| 只拿到第一页 | 未翻页 | 循环到 `currentPage == allPages` |
| 频繁失败 | 触发免费档次限制 | 降速 + 缓存已抓数据 |
## 相关能力 / 下一步阅读
- [古籍查询 API 返回字段全解：trainslation 拼写坑与每个字段含义](https://www.showapi.com/guides/ancient-books-fields-1643)
- [古籍查询 API：5 分钟快速开始（获取古籍目录与明细）](https://www.showapi.com/guides/ancient-books-quickstart-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)
