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로 후보를 보거나, 사용자에게 알고 있는 도서관명·지역을 더 물어본다. 이름만으로 확정되지 않으면 임의로 하나를 고르지 않는다.

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은 신뢰하지 않는다.