kosis ⭐ 추천

통계청 KOSIS에서 인구·산업·시장규모 등 국가 공식 통계를 조회

v0.11.3 릴리즈 v8.48.1 KOSIS statistics population market

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

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

KOSIS_API_KEY 키 등록이 필요합니다.

API 키 발급처: 국가통계포털 KOSIS Open API
발급 절차:
- KOSIS 회원가입
- 상단 메뉴 Open API → 활용신청 → 사용 목적·서비스명 입력 후 신청
- 자동 승인 (즉시 이용 가능) — 별도 대기 없음
- 마이페이지 → 인증키 확인
키 등록 — 발급받은 키를 .env 파일에 넣습니다 (권장). 작업 폴더(Cowork 연결 폴더 / Claude Code 프로젝트 루트)(연결한 폴더가 여러 개면 아무 폴더나) 루트에 .env 파일을 만들고 아래 한 줄을 넣어 두면 스킬이 자동으로 찾아 읽습니다. 점(.)으로 시작하는 파일을 만들기 어렵다면 환경변수.txt 라는 이름으로 만들어도 똑같이 읽힙니다(메모장이 .txt 를 붙여 .env.txt 가 되어도 됩니다).

KOSIS_API_KEY=발급받은_키

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

Claude Desktop의 "Claude 지침"(설정 → 일반)에 같은 내용을 적는 방식도 동작하지만, 대화 컨텍스트에 값이 노출되므로 .env 파일을 권장합니다.

개발자라면 셸 환경변수로 넣어도 됩니다.

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

하고 싶은 것	이렇게 요청하세요
키워드로 통계표 먼저 탐색	`/kosis 인구라는 키워드로 KOSIS 통계표 목록 보여줘`
찾은 통계표 데이터 내려받기	`/kosis 방금 찾은 인구주택총조사 통계표에서 최근 3년 데이터 가져와줘`
인구·경제 핵심 지표 바로 조회	`/kosis 최근 5년 인구주택총조사 총조사인구 데이터 뽑아줘`
GDP 통계	`/kosis 최근 4분기 GDP 통계 정리해줘`
기간 지정 연간 데이터	`/kosis 2020년부터 2024년까지 제조업 생산지수 연간 데이터 뽑아줘`
월별 데이터	`/kosis 최근 12개월 소비자물가지수 월별로 조회해줘`
통계표에 어떤 항목·분류가 있는지 확인	`/kosis 이 통계표에 어떤 항목이랑 분류(성별·연령·지역 등)가 있는지 보여줘`
국제·OECD·세계 통계 찾기	`/kosis OECD 국가별 1인당 GDP 같은 국제통계 목록에서 찾아줘`
통계 작성 배경 확인	`/kosis 이 통계의 작성목적이랑 법적근거, 조사주기 알려줘`
지자체·지역 세부 조회	`/kosis 인천 서구 기준으로 이 통계 조회해줘`

출력 형식을 바꾸고 싶으면 /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가 필요한 항목·분류 코드를 찾아 조회합니다(직접 코드를 외울 필요는 없습니다).

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