nl_search
Search and harvest Korean academic literature and book metadata from the National Library of Korea with filters for title, author, keyword, category, and exact match.
Instructions
[소장자료 검색] 국립중앙도서관 소장자료를 검색한다.
kwd: 검색어.
exact: True 면 큰따옴표 구문검색(토큰 인접 요구). 특정 자료를 정확히 찾을 때만 쓸 것 —
코퍼스 수집에는 부적합하다(아래 참조).
srch_target: 실측 지원값 — title(제목) · author(저자) · publisher(발행자) ·
keyword(키워드) · total(전 필드).
⚠️ isbn·classNo·callNo 등 미지원 값은 오류가 나지 않고 조용히 전 필드 검색으로
폴백한다. ISBN 으로 찾았다고 믿으면 실제로는 전 필드 결과를 받는다
(실측: srchTarget=isbn&kwd=오욱환 이 저자 검색과 같은 36건을 반환).
ISBN 을 찾으려면 srch_target="total" 로 두고 ISBN 문자열을 넣는 편이 정직하다.
category: 도서·고문헌·학위논문·잡지/학술지·신문·기사·멀티미디어·장애인자료·웹사이트·
해외기록물·외부연계자료·기타. ⚠️ "전체" 는 오류(013) — 전체 검색은 생략할 것.
rows: 반환 건수(1~100, 문맥 절약을 위한 도구 자체 상한. API 는 500까지 받는다).
extra_params: 임의 API 파라미터 전달.
⚠️ 기본 검색은 제목 부분일치가 아니라 토큰 매칭 + 적합도 정렬이다.
교육불평등 은 교육·불평등 으로 쪼개져 둘 중 하나만 든 제목도 회수된다.
⚠️ exact=True 는 재현율을 크게 떨어뜨린다 — 실측 6개 검색어에서 평균 47% 손실,
최악 84%(교육형평성 31건 → 5건). 한국어 복합어가 표제에서 조사·수식어로 갈라지기
때문이다(교육의 형평성, 초중등교육의 형평성과) — 구문검색은 인접을 요구한다.
버려지는 것의 76%가 구성어를 모두 포함한 관련 문헌이었다.
→ 자료를 넓게 모을 때는 쓰지 말고, 전체 표제를 아는 특정 자료 조회에만 쓸 것.
AND/OR/NOT 은 연산자가 아니라 그냥 토큰이다(AND 단독 검색 시 451,670건).
⚠️ total 은 국립중앙도서관이 보고한 전체 건수, truncated 는 이번 응답이 그보다 적다는 뜻.
cap_hit=true 는 다르다 — total 이 500을 넘어 501번째부터는 어떤 페이징으로도
받을 수 없다(레코드 오프셋 기준 상한, 실측 확인). 그 경우 검색식을 쪼개야 한다.
빈 records 를 '자료 없음'으로 오독하지 말고 total 을 함께 볼 것.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kwd | Yes | ||
| page | No | ||
| rows | No | ||
| exact | No | ||
| category | No | ||
| srch_target | No | title | |
| extra_params | No |