ISBN 图书 API：精确查询、关键词分页与返回类型

GuGuData ISBN 图书信息 API 可按 ISBN 查询单本图书，也可按书名关键词分页检索，返回书名、作者、出版社、封面及定价等资料。使用 GET；isbn 与 keywords 至少提供一个，精确查询和关键词查询的 Data 类型不同，接入时需要分别处理。

接口概览

项目	说明
请求方法	GET
接口地址	https://api.gugudata.com/text/isbn
返回格式	JSON，UTF-8
调用凭据	对应产品有效 AppKey，本例通过 Header 传递

请求参数

参数名	参数类型	是否必须	默认值	备注
appkey	string	是	无	付费后获取的 APPKEY
isbn	string	否	无	图书 ISBN；与 keywords 参数至少传递一个，如 9787020002320
keywords	string	否	无	图书标题搜索关键字；与 isbn 参数至少传递一个
pageindex	integer	否	1	搜索结果分页参数，第几页
pagesize	integer	否	10	搜索结果分页参数，每页条数，最大值为 10

参数名、大小写与默认值以当前接口文档为准。AppKey 参数的“可选”表示可以改从 Header 提供，不表示无需鉴权。

请求示例

以下是集成示例，未使用真实凭据执行。YOUR_APPKEY 为占位符，正式调用需要有效凭据及对应接口权益，价格与套餐以官网为准。中文 GET 参数通过 URL 编码传递。

curl --get 'https://api.gugudata.com/text/isbn' \
  --header 'X-GUGUDATA-APPKEY: YOUR_APPKEY' \
  --data-urlencode 'isbn=9787020002320'

返回字段

参数名	参数类型	备注
DataStatus.RequestParameter	string	本次实际业务请求参数，不包含鉴权凭据；Demo 展示对应样例输入。
DataStatus.StatusCode	integer	接口返回状态码
DataStatus.StatusDescription	string	接口返回状态说明
DataStatus.ResponseDateTime	string	接口数据返回时间
DataStatus.DataTotalCount	integer	此条件下的总数据量，一般用于分页计算
Data	object | array | null	ISBN 返回单个图书对象，keywords 返回图书对象数组；可靠未找到时为 null。
Data.Title	string	图书名称
Data.CoverImage	string	图书封面图片地址，使用时检查实际可访问性。
Data.ISBN	string	ISBN
Data.Author	string	作者
Data.Translator	string	译者，没有译者时返回空字符串
Data.Publisher	string	出版商
Data.PublisherDateTime	string	出版年月，格式 2022-3
Data.PageNumber	integer	图书总页码
Data.Binding	string	图书包装类型，如平装、精装
Data.BriefIntroduction	string	图书简介
Data.AuthorIntroduction	string	作者简介
Data.Price	number	图书定价，单位：元，仅供参考

字段口径与使用边界

2026 年 11 月 4 日公开 Demo 使用 ISBN 9787020002320，返回图书《三国演义》。以下摘录实际响应的部分字段，不是关键词搜索响应，也不能据此推断其他版本的出版信息或当前售价。

{
  "DataStatus": { "StatusCode": 100, "DataTotalCount": 1 },
  "Data": {
    "Title": "三国演义",
    "ISBN": "9787020002320",
    "Publisher": "人民文学出版社",
    "PublisherDateTime": "1992-2",
    "Price": 13.4
  }
}

ISBN 保留为字符串，避免丢失前导零或 ISBN-10 中的 X；具体可接受的格式按当前文档与实际响应核对。isbn 查询的 Data 是单个对象，keywords 查询的 Data 是对象数组，可靠未找到时为 null；不要对所有响应都直接遍历数组，也不要把依赖异常伪装成未找到。关键词检索使用 pageindex、pagesize，小写参数，每页最多 10 条。PublisherDateTime 是出版年月，可能没有日，不应强制解析成完整日期。Price 是图书定价参考，不是实时成交价、库存或销售报价。

错误与结果核对

先检查 HTTP 状态，再检查 DataStatus.StatusCode；100 表示业务成功。鉴权、参数、额度、限流与依赖异常分别处理，不能把失败转换成“没有结果”。响应时间不等于数据更新时间；缺失字段保留缺口，不补造为零。以当前产品文档、OpenAPI 和订单核对错误码与调用限额。

适合图书资料录入、书目检索和已有 ISBN 的资料补全。匹配时核对版次、作者和出版社，不把同名书直接合并，也不把封面链接等同于图片再分发授权。

官方文档与预览

• 完整接口文档
• 公开数据预览
• 接口 Demo
• 公开 OpenAPI

本文由 GuGuData 产品方整理，接口契约核对日期为 2026 年 11 月 4 日。字段与覆盖范围以当前产品文档为准，未实测的性能与覆盖数量不作保证。

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/fooqiu/article/details/170045601