openlibrary

openlibrary — Open Library の書籍メタデータ

Open Library の 5,000 万件以上のレコードを収録したカタログを、公開 HTTP API 経由で検索します。作品や著者を検索し、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 セッションが必要で、実質的に内部用です。このインターフェースは読み取り専用として扱ってください。

重要なホストは 3 つあり、それぞれ異なるものを提供します。

ホスト	提供内容
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）が含まれます。未知のソート値を指定するとサーバーがプレーンテキストの HTTP 500 を返すため、CLI は --sort の選択肢をクライアント側で検証します。

執筆者を探す — 著者検索

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 は正規版 JSON（/books/<OL…M>.json）へ302 リダイレクトします。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	人間向けのテキストの代わりに、標準出力へ 1 つの JSON オブジェクトを出力します
--dry-run	実行せず、予定されているリクエストを JSON として表示します
--quiet	必須ではない出力を抑制します
--verbose	詳細なログを出力します

複数ステップのパイプライン例

ISBN → 版 → 作品 → 著者の略歴

3 種類すべてのキーをたどる標準的な手順です。

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}'

jq で --json を使う

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 エンドポイントは JSON ではなく 302 を返します — /isbn/<isbn>.json、/lccn/*.json、 /oclc/*.json は /books/<OL…M>.json にリダイレクトします。クライアントはリダイレクトに 従う必要があります（curl -L。requests はデフォルトで対応します）。従わないと、 HTML のリダイレクトページを解析することになります。 /books/<OLID>.json を直接呼び出すと、すぐに 200 が返されます。
• マージされたキーは HTTP 200 のリダイレクトスタブを返します — Open Library はウィキです。 重複した著作物がマージされると、古いキーは 3xx ではなく {"type":{"key":"/type/redirect"},"location":"/works/<master>"} を含む 200 を返し続けます。 成功レスポンス内のスタブの型を検出して再取得してください。同梱の CLI はこれを自動的に 行います（また、拡張子のない URL は HTML ページにリダイレクトされるため、スタブの location に .json を追加します）。
• キーの種類は接尾辞で判別できます — OL…M = 版（/books/）、 OL…W = 著作物（/works/）、OL…A = 著者（/authors/）です。著作物から著者への リンクは二重にネストされています（authors[].author.key）。版ではフラットに ネストされています（authors[].key）。または authors:null の場合もあり、その場合は リンク先の著作物から名前を取得します。誤ったコレクションのキーをリクエストすると、 301 で別の場所にリダイレクトされます。
• 検索結果が空でもエラーではありません — 不正なクエリは緩やかに解析され、numFound:0 を 含む HTTP 200 が返されます。一方、不正な 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/... を使います）。カバーが見つからない場合、?default=false を追加しない限り、 HTTP 200 で空のプレースホルダーが返されます。ID 以外／OLID 以外での検索は、5 分ごとに IP あたり 100 件までで、その後は 403 が返されます。カバー URL は archive.org の ZIP シャードへ 302 でリダイレクトされることがよくあります。
• レート制限はポリシーであり、ヘッダーではありません — Retry-After/X-Rate-Limit ヘッダーはありません。匿名の場合は約 1 req/s です。User-Agent: App (email) を設定すると （OL_EMAIL を設定）、約 3 req/s に上がります。何百件も検索するのではなく、1 回の検索で まとめてください。大量データは月次ダンプを利用してください。
• テキストフィールドは {type,value} オブジェクトにネストされています — 古いレコードでは bio、description、notes が {"type":"/type/text","value":"..."} でラップされている 一方、新しいレコードでは単なる文字列です。どちらにも対応してください。CLI は一元的に ラップを解除します。
• OLID ≠ 長期的な識別子 — 削除されたキーが無関係な書籍に再割り当てされることがあり、 マージで置き換えられたキーはリダイレクトスタブになります。キャッシュでは、OLID と タイトル／ISBN を組み合わせてください。
• スラッグ付き URL では .json の位置が重要です — .json はキーの末尾に追加してください （/authors/OL23919A.json）。スラッグのパスの後には追加しないでください。

使用する場合

• 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 リダイレクト、raw レコードと従来の /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	help、引数エラー、dry-run の計画、モッククライアントのロジック（リダイレクトスタブ、著者のフォールバック、エディションのページネーション）に加え、環境変数で実行を制御するライブプローブを 2 つ（OPENLIBRARY_LIVE_TESTS=1）含む、オフラインの pytest／unittest スイートです。それ以外では外部への通信は発生しません。	.venv/bin/python3 -m pytest -p no:cacheprovider --strict-markers scripts/test_openlibrary.py

前提条件

• Python 3.8 以降と requests（それ以外は標準ライブラリ）。直接実行できない場合は python3 scripts/openlibrary ... として実行してください
• いかなる種類の認証情報も不要です。レート制限への配慮として、任意で OL_EMAIL を設定できます
• --json の後処理には jq を推奨します