library-book-search

圖書館書籍搜尋 (Data4Library)

這個技能做什麼

透過 k-skill-proxy 代理的 HTTP API 查詢國立中央圖書館的 圖書館資訊나루(Data4Library) 開放 API。

• 用關鍵字搜尋書籍。
• 用 ISBN 查看詳細書目及借閱資訊。
• 用 ISBN + 地區代碼找出收藏該書的圖書館清單。
• 用圖書館代碼 + ISBN 確認特定圖書館的館藏/可借閱狀態。

使用時機

• "幫我在圖書館資訊나루找歷史相關的書"
• "找收藏這個 ISBN 的首爾圖書館"
• "確認正讀圖書館有沒有這本書"
• "可以查詢圖書館書籍嗎？"

前置需求

• 網路連線
• 可使用 curl 的環境
• 可存取已設定 DATA4LIBRARY_AUTH_KEY 的 k-skill-proxy 部署（預設 hosted 或 self-host）

憑證需求

使用者不需要任何密鑰，DATA4LIBRARY_AUTH_KEY 僅在代理伺服器端管理。

• 使用者端 無需密鑰。
• KSKILL_PROXY_BASE_URL — 僅在使用 self-host 或獨立代理時設定。留空則使用預設 hosted https://k-skill-proxy.nomadamas.org。
• DATA4LIBRARY_AUTH_KEY 僅放在 代理伺服器 環境中。不要向使用者要求認證金鑰，也不要在回應中暴露。

代理基礎 URL

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

工作流程

1) 收集意圖和最少輸入

根據使用者請求，只詢問必要的值。

• 關鍵字書籍搜尋：只要有 keyword 就開始。
• 詳細查詢：需要 ISBN（10位或13位）。
• 館藏圖書館查詢：需要 ISBN + 廣域地區代碼（region）。如果有市郡區詳細代碼（dtl_region）就一起使用。
• 特定圖書館館藏確認：需要圖書館代碼（libraryCode）+ ISBN。

如果沒有圖書館代碼或地區代碼，先用 library-search 查看候選，或向使用者詢問更多已知的圖書館名稱或地區。如果無法僅憑名稱確定，不要隨意選一個。

2) 搜尋書籍 (/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) 取得書籍詳細資料 (/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) 尋找收藏某本書的圖書館 (/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 是圖書館資訊나루的地區代碼。例如：需要首爾特別市代碼時，使用像 11 這樣的數字代碼。
• 如果有 dtl_region 就進一步縮小範圍。
• 如果結果有多筆，摘要顯示圖書館名稱、地址、網站、電話（如果回應中有），即時可借閱狀態則用獨立的 book-exists 確認。

5) 檢查單一圖書館的館藏 (/v1/data4library/book-exists)

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

• 直接解讀 hasBook、loanAvailable 等 upstream 回應欄位。
• 可借閱狀態可能因圖書館系統同步延遲而不準確，建議最終造訪前先到圖書館網站或電話確認。

6) 選用：圖書館清單 (/v1/data4library/library-search)

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

為使用者摘要

• 先整理書名、作者、出版社、出版年份、ISBN。
• 館藏圖書館清單只顯示根據使用者地區和移動可能性的前幾個候選。
• 不要貼上整段 JSON，而是建議必要的欄位和下一步（詳細查詢/館藏確認/圖書館選擇）。

Upstream 參考

• 圖書館資訊나루 Open API 使用方式：https://www.data4library.kr/apiUtilization

失敗模式

• 代理未設定 DATA4LIBRARY_AUTH_KEY → 503 / upstream_not_configured
• 缺少關鍵字、ISBN、地區代碼、圖書館代碼 → 400 / bad_request
• ISBN 位數錯誤 → 改用不含連字號的 ISBN-10（允許最後為 X）或 ISBN-13 重新請求
• 圖書館代碼/地區代碼不明確 — 向使用者顯示候選並請其選擇
• Data4Library API 暫時故障、呼叫限制、資料未收錄

備註

• 預設姿態是唯讀查詢。不進行預約、借閱或基於個人資訊的圖書館登入自動化。
• DATA4LIBRARY_AUTH_KEY 僅供代理伺服器使用。使用者端沒有密鑰。
• 代理會注入 upstream 的 authKey 和 format=json，因此不信任使用者傳入的 authKey/format。