KOSIS 국가통계포털 사용 가이드

통계청 KOSIS(국가통계포털) 공식 통계를 자연어 한 문장으로 조회하는 스킬입니다. Claude에게 말로 부탁하면 됩니다 — “인구 통계 조회해줘”, “제조업 시장규모 알려줘”, “GDP 최근 데이터 뽑아줘”처럼요. 통계청 코드를 외울 필요는 없습니다.

사전 준비#

KOSIS_API_KEY 키 등록이 필요합니다.

1. API 키 발급처: 국가통계포털 KOSIS Open API
2. 발급 절차:
   • KOSIS 회원가입
   • 상단 메뉴 Open API → 활용신청 → 사용 목적·서비스명 입력 후 신청
   • 자동 승인 (즉시 이용 가능) — 별도 대기 없음
   • 마이페이지 → 인증키 확인
3. 키 등록 — 발급받은 키를 itda-hyve 앱의 시크릿 탭에 KOSIS_API_KEY 이름으로 등록합니다. KOSIS 에 보내는 요청은 사용자 PC 의 itda-hyve 가 대신 보내고, 등록한 키도 itda-hyve 가 그 요청에만 채워 넣습니다. Claude Code 와 Cowork 모두 같은 방법입니다(itda-hyve 가 설치·연결돼 있어야 합니다).

자세한 가입·키 발급 절차는 KOSIS 발급 가이드를 참고하세요.

키 값을 대화창이나 “Claude 지침”에 적지 마세요 — 스킬은 그 값을 쓰지 않고, 대화에 값만 노출됩니다.

인증키는 Base64 형식이라 끝에 = 문자가 붙는 경우가 있습니다. 복사할 때 끝 문자가 잘리지 않도록 전체를 한 번에 복사하세요.

자주 쓰는 요청#

출력 형식#

출력 형식을 바꾸고 싶으면 /kosis 최근 5년 인구 통계 표 형식으로 보여줘처럼 요청하면 됩니다.

팁#

• 검색-조회 2단계를 한 번에: 통계표를 먼저 검색해 ID를 확인해 두면, 동일 통계를 주기적으로 업데이트할 때 재검색 없이 “방금 찾은 통계표로 최근 데이터 다시 뽑아줘”라고 요청하면 됩니다.
• 기간 조회 방식은 하나만: “최근 N개”가 필요하면 개수를 말하고, “특정 연도 구간”이 필요하면 시작과 끝 연도를 말하세요. 두 가지를 동시에 요청하면 한 가지를 우선 적용합니다.
• 기관 ID는 자연어로 말하세요: 통계청 인구(101), 한국은행 경제(301) 같은 기관 코드를 외울 필요 없이 “인구 통계”, “경제 통계”로 요청하면 Claude가 매핑합니다.
• 무엇을 조회할지 모를 때는 구조부터: 원하는 수치가 안 나오면 “이 통계표에 어떤 항목·분류가 있는지 먼저 보여줘”라고 하세요. Claude가 통계표 구조(경제활동인구·취업자 같은 항목, 성별·지역 같은 분류)를 확인한 뒤 정확한 값을 조회합니다.
• API 키 복사 시 패딩 주의: KOSIS 인증키는 Base64 인코딩이라 끝에 = 문자가 붙을 수 있습니다. 복사할 때 끝 문자가 잘리면 인증 실패로 이어지므로 전체를 한 번에 복사하세요.

제한사항#

• ⚠️ 권한 오류 메시지: “활용신청이 필요합니다” 또는 인증키 관련 오류(코드 10/11/42)가 보이면 https://kosis.kr/openapi/ 마이페이지에서 활용 상태와 인증키 만료 여부를 확인하세요. 활용신청은 자동 승인이지만 키가 만료되면 코드 11 오류가 발생합니다.
• ⚠️ 대용량 일괄 조회 미지원: 전국 전 기간·전 항목을 한꺼번에 내려받는 배치 다운로드는 제공되지 않습니다. 기간이나 항목을 나누어 여러 번 조회해야 합니다.
• ⚠️ 실시간 지표 불가: KOSIS는 확정 통계 중심이라 일별·실시간 지표는 없습니다. 가장 빠른 주기는 월별 또는 분기별이며, 발표 시점도 집계 후 1~3개월 이후입니다.
• ⚠️ 복합(다차원) 통계표는 구조 확인이 필요: 3~4중 분류로 설계된 통계표는 “전체”로 요청하면 원하는 값이 안 나올 수 있습니다. 이때는 “이 통계표 항목·분류부터 확인해줘”라고 하면 Claude가 필요한 항목·분류 코드를 찾아 조회합니다(직접 코드를 외울 필요는 없습니다).

안 될 때#