ecos 사용 가이드
한국은행 ECOS(경제통계시스템)에서 거시경제 지표를 조회합니다. Claude에게 자연어로 부탁하면 됩니다 — “GDP 추이 알려줘”, “기준금리와 환율 요약해줘”처럼요. 터미널 명령을 직접 입력할 필요는 없습니다.
사전 준비 — API 키 발급
ECOS 스킬은 한국은행 ECOS Open API 키가 필요합니다.
- 한국은행 경제통계시스템 ECOS Open API에서 회원가입
- Open API → 인증키 신청 → 사용 목적·서비스명 입력 후 제출 → 즉시 발급 (별도 대기 없음)
- 발급받은 키를 itda-hyve 앱의 시크릿 탭에
ECOS_API_KEY이름으로 등록합니다. 키 값은 itda-hyve 에만 저장되고, 스킬과 대화에는 이름만 오갑니다. Claude Code 와 Cowork 모두 같은 방법입니다.
itda-hyve 는 한국은행 서버에 대신 요청을 보내 주는 앱입니다. 아직 없다면 itda-hyve 받는 곳에서 설치하고 Claude Desktop 에 연결하세요.
자세한 가입·키 발급 절차는 ECOS 발급 가이드를 참고하세요.
키 값을 대화창에 붙여 넣지 마세요. 붙여 넣어도 스킬은 그 값을 쓰지 않고 시크릿 탭 등록을 안내합니다.
인증키는 즉시 발급되므로 마감 직전에도 신청할 수 있습니다. 단, 첫 호출 시 수 분간 일시적으로 미반영될 수 있으니 여유를 두세요.
자주 쓰는 요청
| 하고 싶은 것 | 이렇게 요청하세요 |
|---|---|
| 핵심 지표 요약 | /ecos 한국은행 100대 경제지표 보여줘 |
| GDP 추이 | /ecos 최근 5년간 GDP 추이 정리해줘 |
| 금리·환율 | /ecos 기준금리와 환율 요약해줘 |
| 물가 | /ecos CPI 추이 분기별로 가져와 |
| 특정 지표 | /ecos 소비자물가지수 2020년부터 2024년까지 연도별로 표로 정리해줘 |
| 용어 정의 | /ecos GDP디플레이터 용어 정의 가져와서 각주로 넣어줘 |
활용 시나리오
거시경제 지표 시계열 조회
보고서·사업계획서 본문에 인용할 GDP·CPI·기준금리 같은 지표를 기간을 지정해 가져옵니다.
/ecos 최근 5년간 소비자물가지수를 연도별로 표로 정리해줘분기별 데이터가 필요하면 기간과 주기를 함께 말해주세요.
/ecos 2020년 1분기부터 2024년 4분기까지 GDP를 분기별로 가져와100대 경제지표 요약
한국은행이 선정한 핵심 지표를 한 번에 조회해 요약본을 만듭니다.
/ecos 한국은행 100대 경제지표 중 금리 관련 항목만 뽑아줘경제 용어 각주 생성
보고서에 등장한 전문용어를 공식 정의로 각주 처리합니다.
/ecos "GDP디플레이터" 용어 정의 가져와서 각주로 넣어줘
/ecos "기준금리" 공식 정의 알려줘출력 형식 지정
출력 형식을 자연어로 함께 말하면 그에 맞게 정리해 줍니다.
| 원하는 형식 | 이렇게 요청하세요 |
|---|---|
| 사람이 읽기 좋은 표 | /ecos 최근 5년간 GDP 표로 정리해줘 |
| 숫자 배열(차트용) | /ecos 최근 5년간 GDP 차트 그릴 수 있게 숫자 배열로 뽑아줘 |
팁
- 통계 코드를 몰라도 됩니다. 스킬이 자연어 요청을 보고 적절한 통계표를 자동으로 찾아 조회합니다. 다만 조회 결과가 의도와 다르면 “소비자물가지수(CPI)로 다시 조회해줘”처럼 좀 더 구체적으로 말해주세요.
- 기간·주기를 함께 말해주세요. “2020년부터 2024년까지 연도별로”처럼 기간과 주기를 함께 말하면 더 정확하게 조회합니다. 분기별이면 “분기별로”, 월별이면 “월별로”라고 말하면 됩니다.
- 보고서에 바로 붙여넣기. “표로 정리해줘”라고 하면 노션·Obsidian·README에 그대로 붙여넣을 수 있는 마크다운 표 형식으로 돌려줍니다.
- 용어 각주 자동화. 보고서 전문용어를 공식 정의로 한꺼번에 각주 처리할 수 있습니다.
안 될 때
| 증상 | 원인 / 해결 |
|---|---|
“키가 등록되지 않았다”는 안내 (secret_missing) |
itda-hyve 시크릿 탭에 ECOS_API_KEY 가 없음. 위 “사전 준비” 3번 확인 |
“인증키가 유효하지 않다”는 안내 (INFO-100) |
등록한 키 값이 틀렸거나 앞뒤에 공백이 있음. 발급 직후라면 몇 분 뒤 다시 요청 |
“결과를 다 받지 못했다”는 안내 (incomplete) |
결과가 1,000행을 넘어 여러 번에 나눠 받는 중입니다. Claude 가 이어서 받으니 기다리면 됩니다 |
| “통계표를 찾을 수 없습니다” | 요청한 지표가 ECOS에 없거나 표현이 달라 매칭 실패. 다른 표현으로 다시 요청 |
“데이터가 없습니다” (INFO-200) |
기간이나 항목이 없는 경우. 기간을 넓히거나 다른 주기로 다시 요청 |
| 조회 범위 초과 | 너무 긴 기간·세밀한 주기를 한 번에 요청하면 타임아웃될 수 있음. 3~5년 단위로 나눠 요청 |
주의사항
- ⚠️ 실시간 데이터가 아닙니다. ECOS는 확정 통계입니다. 분기 GDP는 약 2개월 뒤, 월별 CPI는 다음 달에 공표되는 등 공표 지연이 있습니다.
- ⚠️ 한국은행 공식 통계 범위만 커버합니다. ECOS에 등록된 통계표만 조회할 수 있습니다. 해당 기관에 없는 지표는 조회되지 않습니다.