calil-books

カーリル図書館APIを使って、図書館の検索と本の貸出状況の照会をするスキル。公式APIで、利用は無料。

実測日: 2026-09-14。本文のコマンド・構造は実測で確認したものを収録(個所ごとの日付は各所の記載を参照)。

APIキーの準備(最初の1回だけ)

1. https://calil.jp/api/dashboard/ でカーリルのアカウントを作り、APIキーを発行する(無料)。
2. キーはチャットやコード、コミットに書かない。環境変数(例: CALIL_APPKEY)に入れて使う。

図書館を検索する

curl -s "https://api.calil.jp/library?appkey=${CALIL_APPKEY}&pref=東京都&format=json&callback=no"

• callback=no を必ず付ける。 付けないと format=json でも応答がJSONP(callback(...) でラップされた形式)で返り、カーリル自身が非推奨と案内している(2026-09-12実測)。JSONPのままでは jq などでそのまま解釈できない。
• pref: 都道府県名。city で市区町村に絞れる。geocode=経度,緯度 でも検索できる。
• レスポンスの systemid が蔵書照会で使う図書館システムのID。libkey は館の略名、formal は正式名称。

デフォルトの対象図書館システム(東京)

ユーザーが東京在住で、対象の図書館を指定しない場合は、東京都立図書館と23区の区立図書館を既定の照会先にする。systemidはカーリルのAPIで実測確認済み(2026-09-14)。

systemid	図書館システム
Tokyo_Pref	東京都立図書館
Tokyo_Chiyoda	千代田区立図書館
Tokyo_Chuo	中央区立図書館
Tokyo_Minato	港区立図書館
Tokyo_Shinjuku	新宿区立図書館
Tokyo_Bunkyo	文京区立図書館
Tokyo_Taito	台東区立図書館
Tokyo_Sumida	墨田区立図書館
Tokyo_Koto	江東区立図書館
Tokyo_Shinagawa	品川区立図書館
Tokyo_Meguro	目黒区立図書館
Tokyo_Ota	大田区立図書館
Tokyo_Setagaya	世田谷区立図書館
Tokyo_Shibuya	渋谷区立図書館
Tokyo_Nakano	中野区立図書館
Tokyo_Suginami	杉並区立図書館
Tokyo_Toshima	豊島区立図書館
Tokyo_Kita	北区立図書館
Tokyo_Arakawa	荒川区立図書館
Tokyo_Itabashi	板橋区立図書館
Tokyo_Nerima	練馬区立図書館
Tokyo_Adachi	足立区立図書館
Tokyo_Katsushika	葛飾区立図書館
Tokyo_Edogawa	江戸川区立図書館

systemid はカンマ区切りで複数指定できるので、都立+23区をまとめて1回で照会できる。

curl -s "https://api.calil.jp/check?appkey=${CALIL_APPKEY}&isbn=9784478025819&systemid=Tokyo_Pref,Tokyo_Setagaya,Tokyo_Shibuya&format=json&callback=no"

別地域のユーザーには、この表を当てはめず、図書館検索(pref / city / geocode)でその地域のsystemidを調べてから照会する。

蔵書・貸出状況を調べる

curl -s "https://api.calil.jp/check?appkey=${CALIL_APPKEY}&isbn=9784478025819&systemid=Tokyo_Setagaya&format=json&callback=no"

• isbn: 10桁または13桁。カンマ区切りで複数指定できる。
• systemid: 図書館検索で得たID。カンマ区切りで複数指定できる。

ポーリング(重要)

蔵書照会は非同期。初回レスポンスが continue: 1 の場合、返ってきた session を付けて2秒以上あけて再取得する。

curl -s "https://api.calil.jp/check?appkey=${CALIL_APPKEY}&session=SESSION_ID&format=json&callback=no"

continue: 0 になるまで繰り返す(数回で終わることが多い)。session 指定の再取得では isbn や systemid は付けない。

結果の読み方

books → ISBN → systemid → libkey の順に、館ごとの状態が入る。

• 貸出可: いま借りられる
• 蔵書なし: その館にない
• 貸出中 / 予約中 / 準備中 / 休館中: いまは借りられない
• 蔵書あり: 状況不明(館に問い合わせ)

reserveurl に予約ページへのURLが入ることがある。

注意

• APIキーは無料だが利用規約がある。商用利用や大量アクセスのルールはカーリルの案内 (https://calil.jp/doc/api.html) を確認する。
• 取得したデータのキャッシュ期間にも規約上の制限がある。恒久的な保存はしない。
• キーを第三者と共有しない。

エラー・失敗時の対応

共通の取得時チェックリストは 共通レスポンス契約 の「取得時の落とし穴チェックリスト」を参照。

• タイムアウトを付ける: curl -sm 30 のように必ず制限時間を付ける。
• ポーリングの上限(重要): continue: 1 が続く場合、最大10回・合計2分程度を上限にする。それを超えたら打ち切り、「図書館APIの照会が混み合っていて結果が返りませんでした。時間をおいてもう一度試してください」とユーザーに伝える。無限にポーリングしない。
• APIキーのエラー: キーが無効・未設定だと正常な結果が返らない。CALIL_APPKEY が設定されているか、キーが正しいかを確認し、「カーリルのAPIキーが無効な可能性があります。https://calil.jp/api/dashboard/ で確認してください」と伝える。
• HTTP 4xx: パラメータかキーの問題。再試行で直らないので、原因を確認してから1回だけやり直す。
• HTTP 5xx / タイムアウト: 1〜2回だけ再試行。直らなければカーリル側の障害の可能性として、 https://calil.jp/ を直接確認するよう案内する。
• 蔵書なし や空の結果はエラーではない: その館に本がない正常な結果として伝える。取得失敗と混同しない。

English summary

Searches library holdings and loan availability across Japan via the Calil Library API. Requires a free API key from https://calil.jp/api/dashboard/ - keep it in an environment variable, never in chat or commits. Availability checks are asynchronous: poll with the returned session at 2+ second intervals, capped at about 10 tries / 2 minutes. The API terms limit long-term caching of results.