カーリル図書館APIでは、全国のOPAC対応図書館のほぼすべてを網羅するリアルタイム蔵書検索機能を提供します。 また、全国の図書館の名称、住所、経緯度情報などをまとめた図書館データベースへのアクセスを提供します。
蔵書検索は、書籍の「ISBN」と、図書館の「システムID」をキーにして検索を行います。
ISBNは、10ケタと13ケタ、ハイフンの有無などいくつかの形式がありますが、図書館APIではどの形式にも対応しています。
システムIDは、各図書館が導入している蔵書管理システムの固有の識別子で「Kanagawa_Fujisawa」のようなアルファベットとアンダーラインによって構成されています。 一つのシステムIDには多くの場合、複数の図書館／図書室が紐付いています。市に一つのシステムIDがあり、市内の全ての図書館・図書室が含まれていることが多いですが、複数の市町村で共同で一つのシステムIDがある場合や、合併などによって一つの市に複数のシステムIDがあることもあります。システムIDは、後述する図書館データベースから取得できます。 本APIで扱う文字コードはUTF-8に統一されています。
APIを利用するには、アプリケーションキーの登録が必要です。 こちらのページでアプリケーションキーを申請してください。
指定した条件で図書館の一覧を取得します。緯度経度を指定した場合は、その地点から近い図書館を順に出力します。
アドレス：https://api.calil.jp/library
パラメータ：
- appkey | (必須) : | アプリケーションキーを指定します。 |
- pref | (任意) : | 都道府県を指定します。例「青森県」 |
- city | (任意) : | 市区町村を指定します。このパラメータはprefとセットで利用します。例「青森市」 |
- systemid | (任意): | 図書館のシステムIDを指定します。例「Aomori_Pref」 |
- geocode | (任意): | 緯度、経度を指定します。例「136.7163027,35.390516」 |
- format | (任意) : | 出力形式を指定します。xmlまたはjsonです。デフォルトはxml |
- callback | (任意) : | JSONPのcallback関数名を指定します。デフォルトはcallback。JSONとして応答する場合はcallbackに空白を指定してください。 |
- limit | (任意) : | 図書館の取得件数を指定します。 |
pref, systemid, geocodeのいずれかは必ず指定する必要があります。
実行例：
https://api.calil.jp/library?appkey={あなたのアプリキー}&pref=埼玉県
https://api.calil.jp/library?appkey={あなたのアプリキー}&geocode=136.7163027,35.390516&limit=10
結果の例：
<?xml version="1.0" encoding="UTF-8"?> <Libraries> <Library> <systemid>Tokyo_NDL</systemid> <systemname>国立国会図書館</systemname> <libkey>東京本館</libkey> <libid>104106</libid> <short>東京本館</short> <formal>国立国会図書館 東京本館</formal> <url_pc>http://www.ndl.go.jp/</url_pc> <address>東京都千代田区永田町1-10-1</address> <pref>東京都</pref> <city>千代田区</city> <post>100-8924</post> <tel>03-3581-2331</tel> <geocode>139.744202,35.6783682</geocode> <category>LARGE</category> <image></image> </Library> </Libraries>
結果の説明：
- systemid | : システムID |
- systemname | : システム名称 |
- libkey | : システム毎の図書館キー |
- libid | : 図書館のユニークID |
- short | : 略称 |
- formal | : 正式名称 |
- url_pc | : PC版ウェブサイト |
- address | : 住所 |
- pref | : 都道府県 |
- city | : 市町村 |
- post | : 郵便番号 |
- tel | : 電話番号 |
- geocode | : 位置情報 |
- category | : カテゴリー（下記参照） |
- image | : 外観写真（現時点では空です） |
- distance | : パラメータでgeocodeが指定されている場合、その地点からの距離(単位：km) |
カテゴリーの凡例は以下の通りです。（アイコンは変わる可能性があります。提供:famfamfam）
| SMALL : |  図書室・公民館 |
| MEDIUM : |  図書館(地域) |
| LARGE : |  図書館(広域) |
| UNIV : |  大学 |
| SPECIAL : |  専門 |
| BM : |  移動・BM |
図書館に対して蔵書の有無と貸出状況を問い合わせます。
アドレス：https://api.calil.jp/check
パラメータ：
- appkey | (必須) : アプリケーションキーを指定します。 |
- isbn | (必須) : 書籍のISBNを指定します。カンマ区切りで複数指定できます。例「4834000826」 |
- systemid | (必須): システムIDを指定します。カンマ区切りで複数指定できます。例「Aomori_Pref」 |
- format | (任意) : 出力形式を指定します。xmlまたはjsonです。デフォルトはjson |
- callback | (任意) : JSONPのcallback関数名を指定します。デフォルトはcallback。JSONとして応答する場合はcallbackにnoを指定してください。 |
isbnは、10ケタ、13ケタどちらも有効です。ハイフンのありなしも問いません。
isbnとsystemidは両者に複数指定することで、同時に複数の書籍を複数の図書館に対して問い合わせることができます。
実行例：
https://api.calil.jp/check?appkey={あなたのアプリキー}&isbn=4834000826&systemid=Aomori_Pref&format=json
結果の例：
callback({
"session": "11a285036112525afe32b1a3d4c36245",
"books": {
"4334926940": {
"Tokyo_Setagaya": {"status": "OK", "reserveurl": "http://libweb.tokyo.jp/123",
"libkey": {"玉川台": "貸出可", "世田谷": "貸出中", "経堂": "館内のみ"}}
},
"4088700104": {
"Tokyo_Setagaya": {"status": "Running", "reserveurl": "",
"libkey": {}}
}
},
"continue": 1
});
結果の説明：
- session : 検索に時間がかかる場合に、セッションが文字列として返ります。
- books : 本毎にどの図書館に蔵書があるか返ります（詳細は後述）。
- continue : 0（偽）または1（真）が返ります。1の場合は、まだすべての取得が完了していないことを示します。
蔵書情報の取得にかかる時間は、各図書館システムによって異なります。1秒以内のところもあれば、遅いシステムだと20秒以上かかるところもあります。
遅いシステムに対応するために、クライアントはcheckを何度かリクエスト（ポーリング）してすべての情報が取得できるまで待つ必要があります。
continueが1で返ってきたときは、クライアントは戻り値のsessionをパラメータにして、再度checkをリクエストします。
そのときのパラメータは以下のようになります。
アドレス：https://api.calil.jp/check
パラメータ：
- appkey (必須) : アプリケーションキーを指定します。
- session (必須) : 取得したセッションを指定します。
- format (任意) : 出力形式を指定します。xmlまたはjsonです。デフォルトはjson
実行例：
https://api.calil.jp/check?session=8e4ee604f3613a3f5f07d5f2d8de86b5&format=json
結果：
2度目以降の呼び出しでも、結果の形式は1度目と同じです。継続を示すcontinueが1（真）であるかぎり、ポーリングを繰り返してください。
continueが0になったら、ポーリングを停止してください。
ポーリングをおこなっている最中の（つまり、continueが1のとき）の戻り値のbooksには、その時点までに取得できた蔵書情報の結果が含まれています。
すべての情報の取得が完了する前に、これらを表示することでユーザーを待たせない工夫ができます。
ポーリングは、かならず2秒以上の間隔をあけて呼び出してください。
checkで返されるbooks配列には、isbnの配列と、ISBN毎にシステムIDの配列が含まれています。
booksは以下のようなデータ構造になっています。
isbn : | ISBNの配列です。 |
- systemid : | システムIDの配列です。 |
- status : | システムIDに対して、検索状態を示します。OK, Cache, Running, Errorの4つをとります。CacheはOKと同じですが内部的にキャッシュ結果が利用されています。 |
- reserveurl : | 予約ページへのアドレスです。 |
- libkey : | システムIDに紐尽く図書館のキーの配列です。図書館館のキー毎に貸出状況（「貸出中」、「貸出可」など）を値として持ちます。蔵書がない場合は、図書館キー自体が配列に含まれず空になります。 |
貸出状況は、以下の8つに分類されます。
貸出可、 蔵書あり、 館内のみ、 貸出中、 予約中、 準備中、 休館中、 蔵書なし「蔵書あり」はデジタルで貸出管理を行っていない図書館の場合などで、蔵書はあるが、貸出状況は不明な場合に返されます。また、図書館システムにより、独自の任意の値（例：「行方不明」「長期延滞」など）を出力することがあります。
これらの情報を元にクライアントは蔵書情報を表示します。
APIを使って取得された図書館名または「蔵書あり」「貸出可」などの貸出状況を表示するときは、かならずカーリルのページに対してリンクを貼らなければなりません。カーリルAPIを使って得た情報からカーリルへリンクする方法を説明します。
各APIは、それぞれ以下のような呼び出し回数の制限があります。 カーリル本体もこの制限の中で動作しており、通常の使用においては問題のない回数となっています。
アプリケーションキーは、こちらから申請してください。