연결 점검 — 인증키 보유 여부 + 자료검색 API 실제 왕복 1회.

[자료검색] 국회도서관의 도서·학위논문·국내외 기사 등 목록DB를 검색한다.

search: 검색항목,키워드 형식이 필수다(그냥 키워드만 넣으면 오류). | 로 여러 개를 연결하면 AND 로 묶인다. 예: 전체,교육|자료명,불평등. OR(합집합)이 필요하면 na_collect(terms=[…]) 를 쓸 것 — 이 API 에 OR 문법은 없다.

검색항목(통합검색 전용 7종): 기본검색 · 전체 · 자료명 · 저자 · 발행자 · 키워드 · 청구기호 🔴 그 밖의 값을 쓰면 오류가 나지 않고 검색어가 통째로 무시되어 전체 카탈로그 13,097,591건이 반환된다. 특히 저자명 은 상세검색(dbname 지정 시)에서는 유효한 이름이라 헷갈리기 쉽다 — 통합검색에서는 반드시 저자 를 쓸 것. 이 도구는 화이트리스트로 미리 막고 오류를 돌려준다.

dbname: 지정하면 상세검색(/detail)으로 전환된다. 21종 중 정확한 문자열이어야 한다: 일반도서 · E-BOOK · 고서 · 세미나자료 · 웹자료 · 학위논문 · 국내기사 · 국외기사 · 학술지,잡지 · 신문 · 전자저널 · 동영상자료 · 오디오자료 · 전자매체 · 마이크로폼자료 · 지도/기타자료 · 외국법률번역DB · 국회회의록 · 국회의안정보 · 표,그림DB · 지식공유 🔴 상세검색은 검색항목 어휘가 DB마다 다르고(학위논문=논문명, 일반도서=자료명, 국내기사=기사명, 국회의안정보=의안명, 국회회의록=안건 …) 통합검색과 달리 틀리면 ERR04 로 실패한다(실측). 이 도구가 호출 전에 검증해 막으므로 정확한 어휘는 na_fields 로 확인할 것.

option: 상세검색 전용. 발행년도,2000|발행년도,2010 (하나면 그 해부터 현재까지, 둘이면 between), 원문유무,1(유)/0(무).

page_size: 한 페이지 건수(최대 1000). 기본은 최대치. max_records: 최대 회수 건수.

⚠️ 회수 한계 99,000건 — pageno 가 최대 99이고 페이지당 최대 1000건이다(실측). total 이 이를 넘으면 응답의 cap_hit 이 참이 되고, 그때는 max_records 를 올려도 더 받을 수 없다(검색식을 쪼개야 한다). truncated 는 max_records 를 올리면 해결된다.

[수집] 검색어들을 각각 조회해 합집합으로 모으고 파일로 저장한다.

terms: 검색항목,키워드 형식의 검색어 목록. 각각 개별 검색 후 합집합(OR)으로 병합한다. 이 API 의 | 는 AND 이므로 OR 은 이렇게 만들어야 한다. 예: ["전체,교육불평등", "전체,교육격차", "자료명,교육 형평성"] search: 단일 검색어(terms 대신).

⚠️ year_from/year_to/contains 는 로컬 후처리다 — 이미 받은 레코드에만 걸리며 회수 한계를 풀어주지 않는다. 서버측 연도 필터는 상세검색의 option 뿐이므로 연도로 범위를 좁히려면 dbname 과 함께 option="발행년도,2000|발행년도,2010" 을 쓸 것.

formats: xlsx/csv/json/sqlite (기본 3종). save=false 면 저장 없이 미리보기만. out_dir 미지정 시 홈의 na-output/.

반환 메타의 cap_hit_terms 는 회수 한계(99,000건)에 걸린 검색어를, incomplete_terms 는 재시도 후에도 실패한 페이지가 있는 검색어를 지목한다 — 둘 다 전수가 아니라는 뜻이다.

[상세정보] 제어번호 1건의 서지정보를 조회한다.

controlno: 검색 결과의 제어번호 (예: MONO12026000012887, KINX2026037525).

🔴 검색 결과(na_search 의 raw)와 필드 집합·값이 완전히 동일하다 — ✅ 실측 (일반도서 19 · 학위논문 18 · 국내기사 13 · 고서 19 · 웹자료 17개 전부 상세전용 필드 0). 즉 이미 검색한 자료라면 이 도구를 부를 이유가 없다. 쿼터(10,000건/일)만 쓴다. 쓸 자리는 제어번호만 아는 자료를 조회할 때다. 목차 본문이 필요하면 na_toc 를 쓸 것 (그쪽은 검색에 없는 내용을 실제로 준다).

⚠️ 존재하지 않는 제어번호도 ERR04 로 응답한다(실측) — 전용 '자료 없음' 코드가 없어 일시 오류와 구분되지 않는다. 실패하면 제어번호부터 확인할 것. ⚠️ 별도 활용신청 대상이다(data.go.kr 15098175). 자료검색 키만으로는 접근할 수 없다.

[목차] 제어번호 1건의 목차정보를 조회한다.

controlno: 검색 결과의 제어번호.

⚠️ 원문은 HTML 이 이스케이프되어 오므로 이 도구가 태그를 풀어 줄바꿈 텍스트로 정리한다. 실제 주력 구분자는 <p> 다(실측 10/10) — 계층은 행 앞 들여쓰기로 표현되므로 그대로 보존해 돌려준다. ⚠️ 목차가 없는 자료도 정상이다. 검색 결과의 목차 필드가 'Y' 인 자료만 부르면 헛호출과 쿼터 낭비를 줄일 수 있다(개발계정 10,000건/일).

🔴 다음 자료종은 목차 가 전건 'N' 이라 이 도구를 부를 이유가 아예 없다(census 실측): E-BOOK · 학술지,잡지 · 신문 · 국외기사 · 동영상자료. 🔴 목차정보없음 센티널 — 플래그가 'Y' 인데 본문이 그 말의 반복인 자료가 있다 (고서에서 표본 5/5). 최대 792자라 길이 검사를 통과하므로 이 도구가 걸러 빈 문자열로 돌려주고, 원문은 envelope.toc_sentinel 에 남긴다.

검색항목·dbname 등 이 API 에서 실제로 통하는 값 목록과 실측 근거.