Calil Books

---
name: calil-books
description: カーリル図書館APIで図書館の蔵書と貸出状況を検索する。蔵書検索、図書館、貸出状況、本を借りたいときに対応。無料APIキーが必要。書籍の購入・電子書籍・国会図書館の検索は対象外。
license: MIT
metadata:
  category: books
  locale: ja-JP
---

# calil-books

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

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

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

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

## 図書館を検索する

```bash
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回で照会できる。

```bash
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を調べてから照会する。

## 蔵書・貸出状況を調べる

```bash
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秒以上あけて再取得する。

```bash
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) を確認する。
- 取得したデータのキャッシュ期間にも規約上の制限がある。恒久的な保存はしない。
- キーを第三者と共有しない。

## エラー・失敗時の対応


共通の取得時チェックリストは [共通レスポンス契約](../docs/response-contract.md) の「取得時の落とし穴チェックリスト」を参照。
- **タイムアウトを付ける**: `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.