图书ISBN查询返回字段全解：一本书的 13 个元数据字段一文读懂
约 8 分钟 入门图书ISBN查询返回字段ISBN元数据API文档
# 图书ISBN查询返回字段全解：一本书的 13 个元数据字段一文读懂
> 接口/接入点：图书ISBN查询（1626-1） · 是否免费：免费 · 请求方式：POST / GET · 返回格式：JSON · 适用人群：所有调用者（字段速查） · 阅读时间：约 6 分钟
## TL;DR
- 业务数据在 `showapi_res_body` 内；系统级字段 `showapi_res_code=0` 表示整体成功。
- `data` 是**单个图书对象**（非数组），含 13 个字段：书名、作者、出版社、出版时间、版次、页数、produce、开本、纸张、装帧、ISBN、定价、内容简介、封面图。
- `ret_code=0` 成功，其他值表示失败/未找到；`remark` 给出错误信息。
## Why
看懂返回结构是写好代码的前提。很多人第一次解析时把 `data` 当数组遍历、或混淆了系统级 `showapi_res_code` 与业务级 `ret_code`，导致拿不到书名。本文把每一层、每一个字段讲清楚，作为全系列的字段速查附录。
## What
接口返回采用"系统级包装 + 业务体"两层结构：
| 层 | 字段 | 类型 | 说明 |
|----|------|------|------|
| 系统级 | `showapi_res_code` | Number | 0 表示请求整体成功 |
| 系统级 | `showapi_res_id` | String | 本次请求唯一 ID |
| 系统级 | `showapi_res_error` | String | 系统级错误信息（成功时为空） |
| 系统级 | `showapi_fee_code` | Number | 计费相关标记（免费接口为 0） |
| 业务体 | `showapi_res_body` | Object | 业务数据均在此对象内 |
`showapi_res_body` 内：
| 字段 | 类型 | 说明 |
|------|------|------|
| `ret_code` | Number | **0 成功**，其他值表示调用失败/未找到 |
| `remark` | String | 错误信息（成功时为 `success`） |
| `data` | Object | **单本图书信息对象**（非数组） |
## How
拿到响应后，先判系统级，再判业务级，最后取 `data`：
```python
import requests
APP_KEY = "YOUR_APPKEY"
resp = requests.post(
"https://route.showapi.com/1626-1",
params={"appKey": APP_KEY},
data={"isbn": "9787208061644"},
timeout=10,
).json()
if resp.get("showapi_res_code") != 0:
raise RuntimeError(resp.get("showapi_res_error"))
body = resp["showapi_res_body"]
if body.get("ret_code") != 0:
print("未找到：", body.get("remark"))
else:
d = body["data"] # 单个对象，不是列表
print(d["title"], d["author"], d["publisher"])
```
## 返回示例与解析（data 字段全表）
`data` 内 13 个字段（名称 / 类型 / 说明 / 示例）：
| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `title` | String | 图书名称 | 追风筝的人 |
| `author` | String | 作者 | 卡勒德·胡赛尼 |
| `publisher` | String | 出版社 | 上海人民出版社 |
| `pubdate` | String | 出版时间 | 2006-05 |
| `edition` | String | 版次 | 1 |
| `page` | String | 页数 | 362 |
| `produce` | String | 文档未给确切定义，示例多为日期（如 2014-7），可能为空 | 2014-7 |
| `format` | String | 开本 | 32开 |
| `paper` | String | 纸张 | 胶版纸 |
| `binding` | String | 装帧 | 平装 |
| `isbn` | String | ISBN 号 | 9787208061644 |
| `price` | String | 定价 | 25.00 |
| `gist` | String | 内容简介 | "许多年过去了……" |
| `img` | String | 封面图下载链接 | http://static1.showapi.com/...jpg |
> 说明：`data` 共 13 个信息字段（含 `isbn` 自身）。`produce` 在文档中描述为占位"请填写参数描述"，实际返回多为日期形态，使用时建议做空值兜底展示。
## 进阶 / 边界
- **`data` 是对象不是数组**：文档文字曾标注为 `Object[]`，但真实返回示例为单个对象，全部文章按"单个对象"解析。
- **两级成功标志**：系统级 `showapi_res_code` 与业务级 `ret_code` 都要判断，二者都为 0 才是真正成功。
- **字段可能为空**：`produce`、`paper` 等字段对部分图书为空，展示端需兜底（如显示"—"）。
## FAQ
**Q1：为什么我按数组遍历 data 取不到数据？**
因为 `data` 是单个对象，不是数组。直接 `data["title"]` 取字段即可。
**Q2：showapi_res_code 和 ret_code 有什么区别？**
前者是系统级（网络/网关层）成功标志，后者是业务层（是否查到书）标志。都要判 0。
**Q3：produce 字段是什么？**
文档未给出确切定义，示例多为出版/印刷相关日期且可能为空；建议按"可选信息"处理，缺失时正常兜底。
**Q4：img 是永久链接吗？**
`img` 为封面图下载链接，建议下载到自己的存储或做前端直链展示（详见封面图篇），不要假设永久不变。
## 相关能力 / 下一步阅读
- [图书ISBN查询：5 分钟接入，从注册到第一条图书信息](https://www.showapi.com/guides/isbn-book-quickstart-1626)
- [图书ISBN查询封面图怎么用：img 字段下载、缓存与展示](https://www.showapi.com/guides/isbn-book-cover-image-1626)
- [图书ISBN查询错误码排查：ret_code 非 0 与"查不到"怎么办](https://www.showapi.com/guides/isbn-book-error-handling-1626)
- **本系列共 12 篇**：查看[图书ISBN查询（apiCode=1626）官方指南总目录](https://www.showapi.com/guides/isbn-book-guides-1626)
