Library Book Search (Data4Library)

What this skill does

国立中央図書館の図書館情報なる(Data4Library) Open APIをk-skill-proxyが中継するHTTP APIで照会する。

• キーワードで図書を検索する。
• ISBNで詳細書誌・貸出情報を確認する。
• ISBN + 地域コードでその図書を所蔵する図書館リストを検索する。
• 図書館コード + ISBNで特定の図書館の所蔵・貸出可能性を確認する。

When to use

• "歴史に関する本を図書館情報なるで探してほしい"
• "このISBNを所蔵している東京の図書館を探してほしい"
• "〇〇図書館にこの本があるか確認してほしい"
• "図書館の図書照会は可能ですか？"

Prerequisites

• インターネット接続
• curlが使用可能な環境
• k-skill-proxyにDATA4LIBRARY_AUTH_KEYが設定されたデプロイ(デフォルトhostedまたはself-host)へのアクセス

Credential requirements

ユーザー側に必要なシークレットはなく、DATA4LIBRARY_AUTH_KEYはプロキシサーバーでのみ管理される。

• ユーザー側必須シークレットなし。
• KSKILL_PROXY_BASE_URL — self-host・別途プロキシを使用する場合のみ設定。空の場合はデフォルトhosted https://k-skill-proxy.nomadamas.org を使用する。
• DATA4LIBRARY_AUTH_KEYはプロキシサーバー環境にのみ置く。ユーザーに認証キーを要求したり、レスポンスに露出させない。

Proxy base URL

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
BASE="${BASE%/}"

Workflow

1) Collect the intent and minimal inputs

ユーザーのリクエストに応じて必要な値のみを質問する。

• キーワード図書検索: keywordがあれば開始する。
• 詳細照会: ISBN(10桁または13桁)が必要。
• 所蔵図書館照会: ISBN + 広域地域コード(region)が必要。市町村詳細コード(dtl_region)があれば併用する。
• 特定図書館の所蔵確認: 図書館コード(libraryCode) + ISBNが必要。

図書館コードや地域コードがない場合は、まずlibrary-searchで候補を表示するか、ユーザーに知っている図書館名・地域をさらに質問する。名前だけでは確定しない場合は、任意に1つを選ばない。

2) Search books (/v1/data4library/book-search)

curl -fsS --get "${BASE}/v1/data4library/book-search" \
  --data-urlencode "keyword=歴史" \
  --data-urlencode "pageNo=1" \
  --data-urlencode "pageSize=10"

別名: q、query、page、limitも許可される。

レスポンスのresponse.docs[].docで主に見るフィールド:

• bookname — 図書名
• authors — 著者
• publisher — 出版社
• publication_year — 出版年
• isbn13 — 詳細・所蔵照会に使用するISBN

3) Fetch book detail (/v1/data4library/book-detail)

curl -fsS --get "${BASE}/v1/data4library/book-detail" \
  --data-urlencode "isbn13=9788971998557" \
  --data-urlencode "loaninfoYN=Y"

• loaninfoYN=Yを指定するとupstreamが提供する人気貸出地域・年齢層・貸出件数などの追加情報をリクエストする。
• 詳細レスポンスが空の場合はISBN誤入力、未収集図書、upstream遅延の可能性を案内する。

4) Find libraries that hold a book (/v1/data4library/libraries-by-book)

curl -fsS --get "${BASE}/v1/data4library/libraries-by-book" \
  --data-urlencode "isbn=9788971998557" \
  --data-urlencode "region=11" \
  --data-urlencode "pageNo=1" \
  --data-urlencode "pageSize=10"

• regionは図書館情報なるの地域コード。例: 東京都コードが必要な場合は13のような数字コードを使用する。
• dtl_regionがあるとさらに絞り込む。
• 結果が複数の場合は図書館名・住所・ホームページ・電話番号(レスポンスにある場合)を要約して表示し、リアルタイム貸出可能性は別途book-existsで確認する。

5) Check one library's holding (/v1/data4library/book-exists)

curl -fsS --get "${BASE}/v1/data4library/book-exists" \
  --data-urlencode "libraryCode=111001" \
  --data-urlencode "isbn13=9788971998557"

• hasBook、loanAvailableなどupstreamレスポンスフィールドをそのまま解釈する。
• 貸出可能性は図書館システムの同期遅延の可能性があるため、最終訪問前に図書館ホームページ・電話で確認することを推奨する。

6) Optional: library list (/v1/data4library/library-search)

curl -fsS --get "${BASE}/v1/data4library/library-search" \
  --data-urlencode "region=11" \
  --data-urlencode "pageNo=1" \
  --data-urlencode "pageSize=10"

Summarize for the user

• 図書名、著者、出版社、出版年、ISBNを最初に整理する。
• 所蔵図書館リストはユーザーの地域・移動可能性を基準に上位候補のみを表示する。
• JSON全体を長く付けず、必要なフィールドと次のステップ(詳細照会・所蔵確認・図書館選択)を提案する。

Upstream reference

• 図書館情報なるOpen API活用方法: https://www.data4library.kr/apiUtilization

Failure modes

• プロキシにDATA4LIBRARY_AUTH_KEY未設定 → 503 / upstream_not_configured
• キーワード・ISBN・地域コード・図書館コード漏れ → 400 / bad_request
• ISBN桁数エラー → ハイフンを除いたISBN-10(最後のXは許可)またはISBN-13で再度リクエスト
• 図書館コード/地域コード不明確 — ユーザーに候補を表示して選択してもらう
• Data4Library API一時障害・呼び出し制限・データ未収集

Notes

• 基本的なposture はread-only照会。予約、貸出、個人情報ベースの図書館ログイン自動化は行わない。
• DATA4LIBRARY_AUTH_KEYはプロキシサーバー専用。ユーザー側にはシークレットがない。
• プロキシがupstream authKeyとformat=jsonを注入するため、ユーザーが渡したauthKey/formatは信頼しない。