---
title: "ecos"
description: "한국은행 ECOS API로 거시경제 지표를 조회하는 스킬입니다. \"GDP 추이 알려줘\", \"금리 환율 정리해줘\", \"100대 경제지표 확인해줘\"처럼 말하면 됩니다. GDP·금리·환율·CPI·100대 핵심 지표 데이터셋을 다룹니다."
pack: itda-gov
slug: ecos
status: active
tags: ["GDP", "ECOS", "CPI", "economics", "interest rate", "exchange rate", "Bank of Korea"]
---
# ecos 사용 가이드

한국은행 ECOS(경제통계시스템)에서 거시경제 지표를 조회합니다.
**Claude에게 자연어로 부탁하면 됩니다** — "GDP 추이 알려줘", "기준금리와 환율 요약해줘"처럼요. 터미널 명령을 직접 입력할 필요는 없습니다.

---

## 사전 준비 — API 키 발급

ECOS 스킬은 한국은행 ECOS Open API 키가 필요합니다.

1. [한국은행 경제통계시스템 ECOS Open API](https://ecos.bok.or.kr/api/)에서 회원가입
2. **Open API → 인증키 신청** → 사용 목적·서비스명 입력 후 제출 → **즉시 발급** (별도 대기 없음)
3. 발급받은 키를 **itda-hyve** 앱의 **시크릿** 탭에 `ECOS_API_KEY` 이름으로 등록합니다. 키 값은 itda-hyve 에만 저장되고, 스킬과 대화에는 이름만 오갑니다. Claude Code 와 Cowork 모두 같은 방법입니다.

itda-hyve 는 한국은행 서버에 대신 요청을 보내 주는 앱입니다. 아직 없다면 [itda-hyve 받는 곳](https://itda.work/hyve/)에서 설치하고 Claude Desktop 에 연결하세요.

> 자세한 가입·키 발급 절차는 [ECOS 발급 가이드](https://itda.work/credentials/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에 등록된 통계표만 조회할 수 있습니다. 해당 기관에 없는 지표는 조회되지 않습니다.