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·별도 프록시를 쓸 때만 설정. 비우면 기본 hostedhttps://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로 후보를 보거나, 사용자에게 알고 있는 도서관명·지역을 더 물어본다. 이름만으로 확정되지 않으면 임의로 하나를 고르지 않는다.
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은 도서관 정보나루 지역코드다. 예: 서울특별시 코드가 필요한 경우11처럼 숫자 코드를 사용한다.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은 신뢰하지 않는다.
