Back to Details

library-book-search

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Library Book Search (Data4Library)

图书馆书籍搜索（Data4Library）

What this skill does

此技能的功能

국립중앙도서관의 도서관 정보나루(Data4Library) Open API를 
k-skill-proxy
가 중계하는 HTTP API로 조회한다.
  • 키워드로 도서를 검색한다.
  • ISBN으로 상세 서지·대출정보를 확인한다.
  • ISBN + 지역코드로 해당 도서를 소장한 도서관 목록을 찾는다.
  • 도서관 코드 + ISBN으로 특정 도서관의 소장/대출 가능 여부를 확인한다.
通过
k-skill-proxy
中转的HTTP API查询韩国国立中央图书馆的图书馆信息宝库(Data4Library) Open API。
  • 通过关键词搜索书籍。
  • 通过ISBN查看详细书目及借阅信息。
  • 通过ISBN+地区代码查找收藏该书的图书馆列表。
  • 通过图书馆代码+ISBN确认特定图书馆是否收藏该书及是否可借阅。

When to use

使用场景

  • "역사 관련 책 도서관 정보나루에서 찾아줘"
  • "이 ISBN 소장한 서울 도서관 찾아줘"
  • "정독도서관에 이 책 있는지 확인해줘"
  • "도서관 도서 조회 가능해?"
  • "帮我在图书馆信息宝库里找历史相关的书"
  • "帮我找首尔收藏这个ISBN的图书馆"
  • "帮我确认正读图书馆有没有这本书"
  • "可以查询图书馆书籍吗？"

Prerequisites

前置条件

  • 인터넷 연결
  • curl
    사용 가능 환경
  • k-skill-proxy
    에 
    DATA4LIBRARY_AUTH_KEY
    가 설정된 배포(기본 hosted 또는 self-host)에 접근 가능할 것
  • 互联网连接
  • 可使用
    curl
    的环境
  • 能够访问已配置
    DATA4LIBRARY_AUTH_KEY
    的
    k-skill-proxy
    部署（默认托管或自托管）

Credential requirements

凭证要求

사용자에게 필요한 시크릿은 없으며, 
DATA4LIBRARY_AUTH_KEY
는 프록시 서버에서만 관리한다.
  • 사용자 측 필수 시크릿 없음.
  • KSKILL_PROXY_BASE_URL
    — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted 
    https://k-skill-proxy.nomadamas.org
    를 사용한다.
  • DATA4LIBRARY_AUTH_KEY
    는 프록시 서버 환경에만 둔다. 사용자에게 인증키를 요구하거나 응답에 노출하지 않는다.
用户无需提供密钥，
DATA4LIBRARY_AUTH_KEY
仅由代理服务器管理。
  • 用户侧无需必备密钥。
  • KSKILL_PROXY_BASE_URL
    — 仅在使用自托管或独立代理时设置。留空则使用默认托管地址
    https://k-skill-proxy.nomadamas.org
    。
  • DATA4LIBRARY_AUTH_KEY
    仅存于代理服务器环境中。不得向用户索要认证密钥或在响应中暴露。

Proxy base URL

代理基础URL

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

Workflow

工作流程

1) Collect the intent and minimal inputs

1) 收集意图与最少输入信息

사용자 요청에 따라 필요한 값만 묻는다.
  • 키워드 도서 검색: 
    keyword
    만 있으면 시작한다.
  • 상세 조회: ISBN(10자리 또는 13자리)이 필요하다.
  • 소장 도서관 조회: ISBN + 광역 지역코드(
    region
    )가 필요하다. 시군구 상세코드(
    dtl_region
    )가 있으면 같이 쓴다.
  • 특정 도서관 소장 확인: 도서관 코드(
    libraryCode
    ) + ISBN이 필요하다.
도서관 코드나 지역코드가 없으면 먼저 
library-search
로 후보를 보거나, 사용자에게 알고 있는 도서관명·지역을 더 물어본다. 이름만으로 확정되지 않으면 임의로 하나를 고르지 않는다.
根据用户请求仅询问必要的信息。
  • 关键词书籍搜索：仅需
    keyword
    即可开始。
  • 详情查询：需要ISBN（10位或13位）。
  • 馆藏图书馆查询：需要ISBN+广域地区代码(
    region
    )。若有市郡区详细代码(
    dtl_region
    )可一并使用。
  • 特定图书馆馆藏确认：需要图书馆代码(
    libraryCode
    )+ISBN。
若没有图书馆代码或地区代码，先通过
library-search
展示候选选项，或进一步询问用户已知的图书馆名称/地区。若仅通过名称无法确定，不得随意选择。

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

2) 搜索书籍（
/v1/data4library/book-search
）

bash
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
bash
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
)

3) 获取书籍详情（
/v1/data4library/book-detail
）

bash
curl -fsS --get "${BASE}/v1/data4library/book-detail" \
  --data-urlencode "isbn13=9788971998557" \
  --data-urlencode "loaninfoYN=Y"
  • loaninfoYN=Y
    를 주면 upstream이 제공하는 인기 대출 지역·연령·대출건수 같은 추가 정보를 함께 요청한다.
  • 상세 응답이 비어 있으면 ISBN 오타, 미수집 도서, upstream 지연 가능성을 안내한다.
bash
curl -fsS --get "${BASE}/v1/data4library/book-detail" \
  --data-urlencode "isbn13=9788971998557" \
  --data-urlencode "loaninfoYN=Y"
  • 指定
    loaninfoYN=Y
    时，会一并请求上游提供的热门借阅地区、年龄、借阅次数等附加信息。
  • 若详情响应为空，需告知用户可能存在ISBN输入错误、书籍未收录或上游延迟的情况。

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

4) 查找收藏书籍的图书馆（
/v1/data4library/libraries-by-book
）

bash
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
    로 확인한다.
bash
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) Check one library's holding (
/v1/data4library/book-exists
)

5) 确认单个图书馆的馆藏情况（
/v1/data4library/book-exists
）

bash
curl -fsS --get "${BASE}/v1/data4library/book-exists" \
  --data-urlencode "libraryCode=111001" \
  --data-urlencode "isbn13=9788971998557"
  • hasBook
    , 
    loanAvailable
    등 upstream 응답 필드를 그대로 해석한다.
  • 대출 가능 여부는 도서관 시스템 동기화 지연이 있을 수 있으므로, 최종 방문 전 도서관 홈페이지/전화 확인을 권한다.
bash
curl -fsS --get "${BASE}/v1/data4library/book-exists" \
  --data-urlencode "libraryCode=111001" \
  --data-urlencode "isbn13=9788971998557"
  • 直接解析上游响应中的
    hasBook
    、
    loanAvailable
    等字段。
  • 由于图书馆系统可能存在同步延迟，建议用户最终前往前通过图书馆官网/电话确认可借阅情况。

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

6) 可选：图书馆列表查询（
/v1/data4library/library-search
）

bash
curl -fsS --get "${BASE}/v1/data4library/library-search" \
  --data-urlencode "region=11" \
  --data-urlencode "pageNo=1" \
  --data-urlencode "pageSize=10"
bash
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 전체를 길게 붙이지 말고, 필요한 필드와 다음 단계(상세 조회/소장 확인/도서관 선택)를 제안한다.
  • 先整理书名、作者、出版社、出版年份、ISBN信息。
  • 馆藏图书馆列表仅展示符合用户所在地区/可到达范围的优先候选。
  • 不要粘贴完整JSON，仅展示必要字段并建议下一步操作（详情查询/馆藏确认/选择图书馆）。

Upstream reference

上游参考

  • 도서관 정보나루 Open API 활용방법: 
    https://www.data4library.kr/apiUtilization
  • 图书馆信息宝库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 일시 장애·호출 제한·데이터 미수집
  • 代理未配置
    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
    은 신뢰하지 않는다.
  • 核心定位为只读查询。不支持预约、借阅、基于个人信息的图书馆登录自动化操作。
  • DATA4LIBRARY_AUTH_KEY
    仅用于代理服务器。用户侧无需密钥。
  • 代理会自动注入上游的
    authKey
    和
    format=json
    参数，因此不信赖用户传入的
    authKey
    /
    format
    参数。