빠른 시작
국가통계포털(KOSIS) 공식 통계를 자연어 한 문장으로 조회하는 가장 간단한 방법입니다.
인구 통계 조회해줘제조업 시장규모 알려줘농업 생산 통계 찾아줘Claude가 요청을 해석해 적절한 기관(org-id)과 통계표(tbl-id)를 자동으로 매칭하고, 최근 데이터를 JSON으로 수집합니다. 사용자가 통계청 코드를 외울 필요는 없습니다.
활용 시나리오
통계표 검색 → 데이터 조회
낯선 주제의 통계를 처음 접근할 때 가장 안전한 순서입니다. 먼저 키워드로 통계표를 찾고, 확인한 ID로 실제 데이터를 내려받습니다.
"인구"라는 키워드로 KOSIS 통계표 목록 먼저 보여줘방금 찾은 인구주택총조사 통계표에서 최근 3년 데이터 가져와줘인구·경제 핵심 지표 바로 조회
자주 쓰는 기관(통계청 인구동향, 한국은행 경제부문 등)은 Claude가 ID를 알고 있으므로, 주제만 말하면 바로 데이터까지 내려받을 수 있습니다.
최근 5년 인구주택총조사 총조사인구 데이터 뽑아줘최근 4분기 GDP 통계 정리해줘기간·주기 지정 조회
사업계획서의 시장 분석 섹션 등 특정 기간의 시계열이 필요할 때 사용합니다.
2020년부터 2024년까지 제조업 생산지수 연간 데이터 뽑아줘최근 12개월 소비자물가지수 월별로 조회해줘출력 옵션
| 옵션 | 설명 | 사용 시점 |
|---|---|---|
| JSON 데이터 (기본) | 메타정보 + 시계열 수치를 구조화해 반환 | LLM이 재가공하거나 보고서·제안서에 인용할 때 |
테이블 형식 (--format table) | 사람이 읽기 편한 표 | 터미널에서 직접 수치를 눈으로 확인할 때 |
통계표 목록 (search 결과) | 통계표명 + org-id + tbl-id 메타 | 아직 어떤 통계표를 쓸지 결정하기 전 탐색 단계 |
팁
- 검색-조회 2단계를 한 번에:
search로 찾은 통계표 ID를 기억해 두면 동일 통계를 주기적으로 업데이트할 때 재검색 없이 바로data로 넘어갈 수 있습니다. Claude에게 “방금 찾은 통계표로 최근 데이터 다시 뽑아줘”라고 요청하면 ID를 재사용합니다. - 기간 옵션은 하나만:
--recent N과--start/--end는 서로 배타적입니다. “최근 N개”가 필요하면--recent, “특정 연도 구간”이 필요하면--start/--end를 사용합니다. - 기관 ID는 자연어로 말하세요: 101(인구), 301(경제) 같은 org-id를 외울 필요 없이 “인구 통계”, “경제 통계”로 요청하면 Claude가 매핑합니다.
- API 키 복사 시 패딩 주의: KOSIS 인증키는 Base64 인코딩이라 끝에
=문자가 붙을 수 있습니다. 복사할 때 끝 문자가 잘리면 인증 실패로 이어지므로 전체를 한 번에 복사하세요.
제한사항
- ⚠️ API 키 승인 지연: KOSIS Open API 신청 후 통계청 승인까지 영업일 기준 1~2일이 걸립니다. 제안서 마감 직전에 신청하면 사용할 수 없으니 미리 발급받아 두세요.
- ⚠️ 대용량 일괄 조회 미지원: 한 번에 전국 전 기간·전 항목을 내려받는 배치 다운로드는 제공되지 않습니다. 기간이나 항목(item)을 나누어 여러 번 조회해야 합니다.
- ⚠️ 실시간 지표 불가: KOSIS는 확정 통계 중심이라 일별·실시간 지표는 없습니다. 가장 빠른 주기는 월별 또는 분기별이며, 발표 시점도 집계 후 1~3개월 이후입니다.
- ⚠️ 복합 통계표의
--item ALL실패: 다차원으로 설계된 통계표에서는--item ALL이 동작하지 않을 수 있습니다. 이런 경우 필요한 항목 코드를 명시적으로 지정해야 합니다.
상세 CLI 레퍼런스
CLI 직접 호출, 서브커맨드·플래그 전체 명세, 오류 코드는 SKILL.md와 references/kosis.md를 참조하세요.