openlibrary

openlibrary — 从 Open Library 获取图书元数据

通过 Open Library 的公开 HTTP API 查询其包含 5,000 多万条记录的目录：搜索作品和作者，按 ISBN 或 OLID 遍历版本／作品／作者关系图，列出所有版本，并查看社区评分。没有 API 密钥；这里的所有操作都是无需密钥的 GET 请求。

设置

无需进行身份验证：公开的 Open Library API 不要求 API 密钥即可读取数据。没有令牌，无需注册，也不必进行延迟身份验证。

# Optional etiquette: identified User-Agent gets ~3x rate budget (~3 req/s vs ~1)
export OL_EMAIL="[email protected]"

需要 Python 3.8+，且仅依赖 requests。无需任何环境配置即可使用 --help 和 --dry-run。上游提供写入端点，但需要经过身份验证的 Internet Archive 会话，实际上属于内部接口——请将此接口视为只读。

有三个重要主机，各自提供不同的内容：

主机	提供内容
openlibrary.org	元数据 JSON：搜索、记录、评分
covers.openlibrary.org	封面图片和作者照片（独立服务）
archive.org	扫描内容／批量转储（重定向目标）

基本命令

查找图书——搜索

openlibrary search --query "dune"                       # relevance order
openlibrary search --query "dune" --sort editions       # most editions first
openlibrary search --query "dune" --sort new            # newest first
openlibrary search --query "foundation" --lang fr       # prefer French editions
openlibrary search --query "dune" --limit 5 --offset 10 # paginate
openlibrary search --query "dune" --json                # machine-readable

结果包含书名、作者、first_publish_year、版本数量，以及供其他命令使用的作品键（/works/OL…W）。CLI 会在客户端验证 --sort 的选项，因为未知的排序值会导致服务器返回纯文本 HTTP 500 错误。

查找作者——作者搜索

openlibrary search-authors --query "asimov"             # name candidates
openlibrary search-authors --query "le guin" --limit 5
openlibrary search-authors --query "asimov" --json      # includes top_work, work_count

作者文档使用不带路径的键（OL23919A），这与图书搜索返回的路径键不同。

查看记录——作者／作品

openlibrary author OL23919A                # bio, dates, photo URL
openlibrary work OL1168083W                # description, subjects, cover URL
openlibrary work OL1168083W --json         # full record

可以传入裸键（OL23919A），也可以传入路径（/authors/OL23919A）——CLI 会统一处理这两种格式。

解析 ISBN

openlibrary isbn 9780451524935             # ISBN-10 or ISBN-13
openlibrary isbn 9780451524935 --json      # + resolved edition_key, work_keys, cover_url

在上游，/isbn/<isbn>.json 会返回 302 重定向，指向规范版本 JSON（/books/<OL…M>.json）。CLI 会跟随重定向，并通过 edition_key 报告匹配到的版本。如果版本记录中缺少作者姓名（有些记录中的 authors 为 null），CLI 会从关联的作品中补全作者信息。

列出某部作品的所有版本

openlibrary editions OL81699W                          # publisher/date/ISBN per edition
openlibrary editions OL81699W --limit 50 --offset 50   # page through large sets
openlibrary editions OL81699W --json                   # + next_offset when more exist

此命令通过 /works/<key>/editions.json 获取数据；next_offset 根据服务器预先生成的下一页链接计算。

了解读者反馈——社区信号

openlibrary ratings OL45804W               # average rating + shelf counts
openlibrary ratings OL45804W --json        # full distribution + bookshelves

该命令会合并 /works/<key>/ratings.json（summary.average、各星级的 counts）和 /works/<key>/bookshelves.json（want_to_read、currently_reading、already_read）中的数据。

全局标志

位置不限；可放在子命令前后：

openlibrary --json search --query "dune"     # machine output anywhere
openlibrary --dry-run isbn 9780451524935     # preview the exact URL, no network
openlibrary --quiet search --query "dune"    # suppress diagnostics

标志	效果
--json	在 stdout 输出一个 JSON 对象，而非人类可读文本
--dry-run	以 JSON 格式打印计划执行的请求，但不实际执行
--quiet	隐藏非必要输出
--verbose	详细日志

多步骤流水线示例

ISBN → 版本 → 作品 → 作者简介

遍历全部三种键类型的规范路径：

openlibrary isbn 9780451524935 --json | jq -r '.work_keys[0]'   # OL1168083W
openlibrary work OL1168083W --json | jq -r '.authors[0]'        # bare OL…A key
openlibrary author OL118077A                                    # bio, dates

CLI 会确保此流水线的类型安全：所有在 --json 下输出 authors 字段的命令（isbn、work）都会采用相同的数据结构——由不带路径的 OL…A 键组成的数组；而人类可读输出则会将标签以逗号分隔的形式呈现。每一步使用不同的键后缀（M → W → A）；如需自行拼接这些 URL，请先查看“已知注意事项”。

按社区喜爱程度为系列排名

for w in $(openlibrary search --query 'series:dune' --limit 8 --json | jq -r '.results[].key'); do
  openlibrary ratings "${w##*/}" --json \
    | jq -c '{work: .key, avg: .average, rated: .ratings_count,
              want_to_read: .bookshelves.want_to_read}'
done

查找可读的电子书，再查找其印刷版

openlibrary search --query 'title:"moby dick"' --sort editions --json \
  | jq '.results[] | select(.has_fulltext) | {title, key}'
openlibrary editions OL81699W --json | jq '.editions[] | {key, isbn_13}'

使用 --json 和 jq

openlibrary search --query "voracious" --json | jq '.results[] | {title, first_publish_year}'
openlibrary search-authors --query "butler" --json | jq '.results[0] | {name, key, top_work}'
openlibrary isbn 9780451524935 --json | jq -r '.cover_url'          # covers host URL
openlibrary editions OL81699W --json | jq '[.editions[].publish_date]'
openlibrary ratings OL45804W --json | jq '.rating_distribution'

已知注意事项

• ISBN 端点返回 302，而非 JSON — /isbn/<isbn>.json、/lccn/*.json、 /oclc/*.json 会重定向到 /books/<OL…M>.json。客户端必须跟随重定向 （curl -L；requests 默认会跟随），否则会解析 HTML 重定向页面。 直接调用 /books/<OLID>.json 会立即返回 200。
• 合并后的键会在 HTTP 200 响应中返回重定向存根 — Open Library 是一个 wiki； 重复作品合并时，旧键仍会返回 200，内容为 {"type":{"key":"/type/redirect"},"location":"/works/<master>"}，而不是 3xx。请在成功响应中检测存根类型并重新获取。捆绑的 CLI 会自动处理 （并在存根位置后添加 .json，因为不带扩展名的 URL 会重定向到 HTML 页面）。
• 键类型编码在后缀中 — OL…M = 版本（/books/）， OL…W = 作品（/works/），OL…A = 作者（/authors/）。作品中的作者链接 是双层嵌套（authors[].author.key）；版本中的作者链接是扁平嵌套 （authors[].key），也可能完全没有 authors（值为 null），此时可从 关联作品中找回作者姓名。使用错误的集合请求某个键会触发 301 重定向。
• 搜索结果为空不代表错误 — 格式错误的查询会被宽松解析，并以 HTTP 200 返回 numFound:0；相反，无效的 sort= 枚举值会返回纯文本 HTTP 500，非整数的 limit 会返回 FastAPI 422。请根据响应正文进行判断，而不只是查看状态码。
• availability 需要 ia — 在原始 /search.json 调用中，如果同时没有请求 ia，请求 fields=availability 会静默地不返回任何内容。
• 封面托管在另一台主机上 — 图片 URL 始终为 covers.openlibrary.org/b/id/<cover_id>-{S,M,L}.jpg（作者照片使用 /b/isbn/...、 /a/id/...）。缺失的封面会返回空白占位图，状态码为 HTTP 200，除非添加 ?default=false；非 ID、非 OLID 查询每 IP 每 5 分钟最多 100 次请求，之后返回 403； 封面 URL 通常会 302 重定向到 archive.org 的 zip 分片。
• 速率限制属于政策，而非响应头 — 不存在 Retry-After/X-Rate-Limit 响应头。 匿名请求约为 1 req/s；设置 User-Agent: App (email)（通过 OL_EMAIL 设置） 后可提高到约 3 req/s。请通过一次搜索批量查询，而不是进行数百次查找； 批量数据应使用每月数据转储。
• 文本字段嵌套 {type,value} 对象 — 较早的记录会将 bio、 description、notes 包装为 {"type":"/type/text","value":"..."}，而较新的 记录使用纯字符串。请同时处理这两种格式；CLI 会在统一位置解包。
• OLID 不等于长期身份标识 — 已删除的键可能会重新分配给无关书籍，合并后废弃的键 则会变成重定向存根。在任何缓存中，都应将 OLID 与书名或 ISBN 配对。
• 带 slug 的 URL 中 .json 的位置很重要 — 将 .json 添加到裸键后 （/authors/OL23919A.json），切勿放在 slug 路径之后。

适用场景

• 关于 Open Library 公共目录能够回答的书籍、作者或作品问题
• 将 ISBN/OLID 键解析为规范记录，并遍历版本、作品和作者关系图
• 查找可阅读或可借阅的扫描件、封面图片、社区评分和书架数量

不适用场景

请勿将此技能用于本地图书馆目录管理——Koha/Evergreen ILS 配置、MARC 批处理、读者管理——也不要用于授权商业数据源（ISBNdb、Google Books）、 引文格式设置，或管理你自己的 Open Library 阅读账户/书单（这需要登录网站，而此技能 有意不处理此类操作）。电影/电视元数据请使用 tmdb。

参考文件

文件	主题	阅读时机
references/api-overview-and-key-graph.md	访问模型、速率限制规范、OLID M/W/A 键图、跨集合 301 重定向、合并占位记录处理、{type,value} 文本包装	手动拼接记录 URL、处理合并或键错误，或规划请求频率时
references/search-api-guide.md	/search.json 参数、排序键、字段范围（title:、isbn: 等）、fields= 投影（包括 availability/ia 交互）、/search/authors.json、/subjects/<name>.json、书内搜索、错误模型	构建精确查询、翻页获取大量结果，或排查空结果时
references/books-isbn-and-covers.md	标识符端点及其 302 解析、原始记录与旧版 /api/books 视图模型、版本列表、评分/书架数据结构、封面主机 URL 规则与限制	使用 ISBN/LCCN/OCLC、枚举版本或获取图片时
references/recipes-and-gotchas.md	端到端 curl/jq 管道（ISBN→作品→作者链、电子书发现、封面拼接、消歧），以及按症状索引的常见问题表	搭建多步骤工作流或诊断意外响应时

可用脚本

脚本	用途	调用方式
scripts/openlibrary	本技能调用的 CLI：search、search-authors、author、work、isbn、editions、ratings——均支持 --json/--dry-run、自动解析 302 和合并占位记录、解包 {type,value}、拼接封面主机 URL，并在客户端校验排序。处理上述图书元数据问题时请运行此脚本。	scripts/openlibrary search --query "dune" --json
scripts/test_openlibrary.py	离线 pytest/unittest 测试套件，涵盖帮助信息、参数错误、dry-run 计划、模拟客户端逻辑（重定向占位记录、作者回退、版本翻页），以及两个受环境变量控制的在线探测（OPENLIBRARY_LIVE_TESTS=1）。其他情况下不会产生外部网络请求。	.venv/bin/python3 -m pytest -p no:cacheprovider --strict-markers scripts/test_openlibrary.py

前置条件

• Python 3.8+ 和 requests（否则使用标准库）；如果无法直接执行，请通过 python3 scripts/openlibrary ... 调用
• 无需任何凭据；可选设置 OL_EMAIL 以遵循速率限制规范
• 建议使用 jq 进行 --json 后处理