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

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

사전 준비

KOSIS_API_KEY 키 등록이 필요합니다.

API 키 발급처: 국가통계포털 KOSIS Open API
발급 절차:
- KOSIS 회원가입
- 상단 메뉴 Open API → 활용신청 → 사용 목적·서비스명 입력 후 신청
- 자동 승인 (즉시 이용 가능) — 별도 대기 없음
- 마이페이지 → 인증키 확인
키 등록 — 발급받은 키를 Claude Desktop 지침에 추가합니다. Claude Desktop → 설정 → 일반 → “Claude 지침” 에 아래 한 줄을 붙여넣고 저장하세요.

KOSIS_API_KEY=발급받은_키

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

한 번 넣으면 이후 모든 대화에서 Claude가 자동으로 사용합니다 — .env 같은 파일을 직접 만들 필요가 없습니다.

개발자라면 작업 폴더 루트의 .env에 같은 한 줄을 넣어도 됩니다.

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

하고 싶은 것	이렇게 말하세요
키워드로 통계표 먼저 탐색	”인구라는 키워드로 KOSIS 통계표 목록 보여줘”
찾은 통계표 데이터 내려받기	”방금 찾은 인구주택총조사 통계표에서 최근 3년 데이터 가져와줘”
인구·경제 핵심 지표 바로 조회	”최근 5년 인구주택총조사 총조사인구 데이터 뽑아줘”
GDP 통계	”최근 4분기 GDP 통계 정리해줘”
기간 지정 연간 데이터	”2020년부터 2024년까지 제조업 생산지수 연간 데이터 뽑아줘”
월별 데이터	”최근 12개월 소비자물가지수 월별로 조회해줘”

출력 형식을 바꾸고 싶으면 Claude에게 “표 형식으로 보여줘”처럼 말하면 됩니다.

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

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

증상	원인 / 해결
”API 키가 설정되지 않았습니다”	Claude 지침(또는 `.env`)에 `KOSIS_API_KEY=키` 누락. 위 “사전 준비” 확인
”통계표를 찾을 수 없습니다”	기관 ID·통계표 ID 오류. Claude에게 “통계표 먼저 검색해줘”로 재탐색
”데이터가 없습니다”	기간 또는 항목 오류. 기간이나 항목을 조정해 재시도
인증키 오류 코드 11	인증키 기간만료. 마이페이지에서 기간 연장
조회결과 없음 (코드 30)	조회 조건(기간/항목) 조정 필요
서버오류 (코드 50)	잠시 후 재시도