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

이 API 를 쓸 때 알아야 할 것 — 서비스뷰·주기·메타 종류·한계·함정.

통계표를 이름·내용으로 찾는다(KOSIS 통합검색).

Args: query: 검색어(예: '사교육비', '출산율'). max_records: 돌려줄 최대 건수.

통계목록 트리를 한 단계 훑는다(주제별·기관별 등).

Args: vw_cd: 서비스뷰 코드. kosis_guide 의 서비스뷰 참조. parent_id: 상위 목록 ID. 비우면 최상위가 온다(개발가이드는 필수라 하지만 실제로는 생략 가능 — 실측).

통계표의 메타자료 — 항목(ITM)·수록기간(PRD)·출처(SOURCE)·주석(CMMT) 등.

⚠️ kosis_data 를 부르기 전에 ITM 으로 항목 ID 를, PRD 로 수록주기를 확인하면 err 20/21 을 피할 수 있다. 🔴 분류축을 알려 주는 종류는 없다. NCD 는 분류가 아니라 신규수록 시점이고 OBJ·CLS 는 err 30 이다(실측) — 축은 kosis_data 가 알아서 맞춘다. ⚠️ 없는 kind 는 err 21 이 아니라 err 30(0건)으로 오므로 오타가 '자료 없음'처럼 보인다. 그래서 아는 종류만 받는다 — 가능한 값은 kosis_guide 의 메타_종류.

통계설명(조사개요) — 목적·근거·주기·범위 등.

통계표에는 초록이 없으므로, 관련도 채점이나 요약이 필요할 때 이 설명이 재료다.

통계표의 수치를 받는다.

🔴 분류축이 여럿인 표(예: 산업 × 규모)도 그냥 부르면 된다. KOSIS 는 요청의 분류축 개수가 표의 축 개수와 정확히 맞기를 요구하는데(모자라면 err 20 (objL), 넘치면 err 21) 축 개수를 알려 주는 메타가 없다. 그래서 이 도구가 축을 하나씩 늘려 가며 맞춘다 — 결과의 meta.obj_levels 에 확정된 축이 실린다.

Args: org_id: 기관 ID(예: '101'). tbl_id: 통계표 ID(예: 'DT_1B040A3'). prd_se: 수록주기 — Y(년)·H(반기)·Q(분기)·M(월)·D(일). kosis_meta(kind='PRD') 로 확인. start, end: 시점 범위(예: '202101''202512'). 🔴 이 방식이면 4만 셀을 넘어도 자동으로 기간을 쪼개 전수를 받는다. recent: 최근 N개 시점. start/end 대신 쓴다(이 방식은 자동 분할이 안 된다). obj_l1: 분류1 — 'ALL' 전체, '11' 특정, '11*' 하위 전체, '11+21' 여럿. obj_l2 ~ obj_l8: 분류28. 비워 두면 필요한 만큼 'ALL' 로 자동으로 채운다. 4만 셀(err 31)에 걸릴 때 특정 코드로 좁히는 자리이기도 하다. items: 항목 — 'ALL' 또는 항목 ID(kosis_meta(kind='ITM')). max_rows: 돌려줄 최대 행 수(파일로 받으려면 kosis_collect).

통계표 하나를 서지(인용) 칸으로 투영한다 — 선택 기능.

⚠️ 이 도구는 부가 기능이다. 통계를 쓰는 것이 목적이면 kosis_search(표 메타)와 kosis_data(수치)가 본령이고, 이 도구는 서지관리 도구로 넘길 때만 쓴다.

KOSIS 는 조사(STAT_NM)와 표(TBL_NM) 두 층을 다 주므로 어느 층으로 인용할지는 부르는 쪽이 고른다 — container_title 이 조사층, title 이 표층이다.

Args: accessed: 조회일자(YYYY-MM-DD). 데이터셋 인용에는 조회일자가 필요하다.

통계표 수치를 받아 xlsx/csv/json/sqlite 로 저장한다.

⚠️ 분류 축이 표마다 다르므로 열 구성이 가변이다 — 분류 이름이 그대로 열이 된다. 축 개수도 표마다 다르지만 obj_l2~obj_l8 을 비워 두면 자동으로 맞춘다.

주요지표를 이름으로 찾는다 — 통계표와는 다른 계열이다.

KOSIS 는 통계표(TBL_ID) 말고 지표(statJipyoId) 계열을 따로 둔다(합계출산율, 추계인구 …). 표 구조를 몰라도 바로 값을 볼 수 있는 대신, 지표로 큐레이션된 것만 있다. 표 단위로 파고들 거라면 kosis_search 를 쓴다.

🔴 이 계열에만 페이징이 있고 안 주면 서버가 10건에서 자른다 — 이 도구가 끝까지 넘겨 전수를 회수한다(meta.pages 에 몇 쪽을 읽었는지 실린다).

Args: name: 지표명(예: '출산율', '인구'). jipyo_id: 지표ID 로 직접 찾을 때(둘 중 하나는 필요). max_records: 돌려줄 최대 건수.

주요지표의 시점별 수치를 받는다.

🔴 KOSIS 가 이 계열에서는 시점 범위를 거르지 않는다. startPrdDe/endPrdDe 는 값이 무시되고 모드 스위치로만 작동해서, 무엇을 주든 전 구간이 온다(실측). 그래서 이 도구가 전 구간을 받아 직접 거르고, 그 사실을 meta.server_filtered (=false)와 meta.filter_note 로 알린다 — 서버가 걸러 줬다고 믿으면 요청하지 않은 구간을 받고도 모른다.

Args: jipyo_id: 지표ID(kosis_indicator_search 로 찾는다). start, end: 시점 범위(예: '2015'~'2025'). 비우면 전 구간. recent: 최신 N개 시점만(start/end 를 안 줬을 때).