ecos

README

ecos-go

한국은행 경제통계시스템(ECOS) OpenAPI 의 Go 클라이언트 라이브러리.

설치

go get github.com/kenshin579/ecos-go@latest

Go 1.25+, 외부 의존성 없음(표준 라이브러리만).

사용

client, _ := ecos.NewClientFromEnv() // ECOS_API_KEY
ctx := context.Background()

// 한국은행 기준금리 (일별)
res, _ := client.StatisticSearch(ctx, ecos.SearchParams{
    StatCode: "722Y001", Cycle: ecos.CycleDaily,
    Start: "20260101", End: "20260131", ItemCode1: "0101000",
})
for _, r := range res.Rows {
    v, _ := r.Float64()
    fmt.Println(r.Time, v, r.UnitName)
}

// 전 페이지 자동 수집
rows, _ := client.StatisticSearchAll(ctx, ecos.SearchParams{
    StatCode: "722Y001", Cycle: ecos.CycleDaily,
    Start: "20200101", End: "20261231", ItemCode1: "0101000",
})

// 100대 통계지표
keys, _ := client.KeyStatisticList(ctx, ecos.KeyStatisticListParams{})

인증

https://ecos.bok.or.kr/api/ 에서 발급받은 인증키를 ECOS_API_KEY 환경변수로 두거나 ecos.NewClient(apiKey) 로 전달한다.

옵션

client, _ := ecos.NewClient(apiKey,
    ecos.WithTimeout(10*time.Second),  // HTTP 타임아웃 (기본 30s)
    ecos.WithLanguage("en"),           // 언어구분 kr/en (기본 kr)
    ecos.WithBaseURL("https://..."),   // 베이스 URL 교체 (테스트/프록시)
    ecos.WithHTTPClient(custom),       // *http.Client 주입
)

커버리지

ECOS OpenAPI 6개 서비스 전체.

서비스	메서드	설명
StatisticTableList	client.StatisticTableList	통계표 목록
StatisticWord	client.StatisticWord	통계용어사전
StatisticItemList	client.StatisticItemList	통계 세부항목 목록
StatisticSearch	client.StatisticSearch / StatisticSearchAll	통계 데이터 조회
KeyStatisticList	client.KeyStatisticList	100대 통계지표
StatisticMeta	client.StatisticMeta	통계메타DB

요청·응답 명세는 docs/api/ 참고 (실 API 응답 대조로 작성).

에러 처리

• errors.Is(err, ecos.ErrNoData) — 데이터 없음 (INFO-200)
• errors.As(err, &apiErr) — 그 외 ECOS 오류 (*ecos.APIError, Code/Message)

에러 메시지에 인증키는 노출되지 않는다.

예제

ECOS_API_KEY=... go run ./examples/basic

License

Released under the MIT License.

Documentation

Overview

Package ecos 는 한국은행 ECOS OpenAPI 의 Go 클라이언트다.

Index

• Variables
• type APIError
• type Client
  • func NewClient(apiKey string, opts ...Option) (*Client, error)
  • func NewClientFromEnv(opts ...Option) (*Client, error)
  • func (c *Client) KeyStatisticList(ctx context.Context, p KeyStatisticListParams) (*KeyStatisticListResult, error)
  • func (c *Client) StatisticItemList(ctx context.Context, p ItemListParams) (*ItemListResult, error)
  • func (c *Client) StatisticMeta(ctx context.Context, p MetaParams) (*MetaResult, error)
  • func (c *Client) StatisticSearch(ctx context.Context, p SearchParams) (*SearchResult, error)
  • func (c *Client) StatisticSearchAll(ctx context.Context, p SearchParams) ([]SearchRow, error)
  • func (c *Client) StatisticTableList(ctx context.Context, p TableListParams) (*TableListResult, error)
  • func (c *Client) StatisticWord(ctx context.Context, p WordParams) (*WordResult, error)
• type Cycle
• type ItemListParams
• type ItemListResult
• type ItemRow
• type KeyStatRow
  • func (r KeyStatRow) Float64() (float64, error)
• type KeyStatisticListParams
• type KeyStatisticListResult
• type MetaParams
• type MetaResult
• type MetaRow
• type Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithLanguage(lang string) Option
  • func WithTimeout(d time.Duration) Option
• type Page
• type SearchParams
• type SearchResult
• type SearchRow
  • func (r SearchRow) Float64() (float64, error)
• type TableListParams
• type TableListResult
• type TableRow
• type WordParams
• type WordResult
• type WordRow

Variables

var ErrNoData = httpclient.ErrNoData

ErrNoData 는 INFO-200 (해당하는 데이터가 없습니다).

Types

type APIError

type APIError = httpclient.APIError

APIError 는 ECOS RESULT 실패 응답. errors.As 로 Code/Message 접근.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client 는 ecos 라이브러리의 단일 진입점.

func NewClient

func NewClient(apiKey string, opts ...Option) (*Client, error)

NewClient 는 API 키로 Client 를 만든다.

func NewClientFromEnv

func NewClientFromEnv(opts ...Option) (*Client, error)

NewClientFromEnv 는 ECOS_API_KEY 환경변수로 Client 를 만든다.

func (*Client) KeyStatisticList

func (c *Client) KeyStatisticList(ctx context.Context, p KeyStatisticListParams) (*KeyStatisticListResult, error)

KeyStatisticList 는 100대 통계지표의 최신 값을 조회한다.

func (*Client) StatisticItemList

func (c *Client) StatisticItemList(ctx context.Context, p ItemListParams) (*ItemListResult, error)

StatisticItemList 는 통계표의 세부 항목 목록을 조회한다.

func (*Client) StatisticMeta

func (c *Client) StatisticMeta(ctx context.Context, p MetaParams) (*MetaResult, error)

StatisticMeta 는 통계메타DB 를 데이터명으로 조회한다.

func (*Client) StatisticSearch

func (c *Client) StatisticSearch(ctx context.Context, p SearchParams) (*SearchResult, error)

StatisticSearch 는 통계 데이터를 조회한다.

func (*Client) StatisticSearchAll

func (c *Client) StatisticSearchAll(ctx context.Context, p SearchParams) ([]SearchRow, error)

StatisticSearchAll 은 list_total_count 기준으로 전 페이지를 자동 수집한다. p.Page 는 무시된다. 페이지 경계에서 INFO-200 이 오면 수집분을 반환한다.

func (*Client) StatisticTableList

func (c *Client) StatisticTableList(ctx context.Context, p TableListParams) (*TableListResult, error)

StatisticTableList 는 통계표 목록을 조회한다.

func (*Client) StatisticWord

func (c *Client) StatisticWord(ctx context.Context, p WordParams) (*WordResult, error)

StatisticWord 는 통계 용어 정의를 검색한다.

type Cycle

type Cycle string

Cycle 은 통계 주기 코드. 날짜 형식은 docs/api/README.md 참고.

const (
	CycleAnnual      Cycle = "A"  // 년 (YYYY)
	CycleSemiAnnual  Cycle = "S"  // 반년 (YYYYSn) — 희소/레거시
	CycleQuarterly   Cycle = "Q"  // 분기 (YYYYQn)
	CycleMonthly     Cycle = "M"  // 월 (YYYYMM)
	CycleSemiMonthly Cycle = "SM" // 반월 (YYYYMMSn) — 희소/레거시
	CycleDaily       Cycle = "D"  // 일 (YYYYMMDD)
)

type ItemListParams

type ItemListParams struct {
	Page     Page   // 제로값은 1~100
	StatCode string // 필수 — 통계표코드
}

ItemListParams 는 StatisticItemList(통계세부항목목록) 요청 인자.

type ItemListResult

type ItemListResult struct {
	TotalCount int
	Rows       []ItemRow
}

ItemListResult 는 통계세부항목목록 응답.

type ItemRow

type ItemRow struct {
	StatCode  string `json:"STAT_CODE"`   // 통계표코드
	StatName  string `json:"STAT_NAME"`   // 통계명
	GrpCode   string `json:"GRP_CODE"`    // 항목 그룹코드 (Group1~ = 항목코드1~4 위치)
	GrpName   string `json:"GRP_NAME"`    // 항목 그룹명
	ItemCode  string `json:"ITEM_CODE"`   // 통계항목코드 (StatisticSearch 에 사용)
	ItemName  string `json:"ITEM_NAME"`   // 통계항목명
	PItemCode string `json:"P_ITEM_CODE"` // 상위 통계항목코드 (최상위는 null→"")
	PItemName string `json:"P_ITEM_NAME"` // 상위 통계항목명
	Cycle     string `json:"CYCLE"`       // 주기
	StartTime string `json:"START_TIME"`  // 수록 시작일자 (주기별 날짜 형식)
	EndTime   string `json:"END_TIME"`    // 수록 종료일자
	DataCnt   int    `json:"DATA_CNT"`    // 자료 수
	UnitName  string `json:"UNIT_NAME"`   // 단위
	Weight    string `json:"WEIGHT"`      // 가중치 (없으면 null→"")
}

ItemRow 는 통계세부항목목록 응답 행. docs/api/통계세부항목목록.md 참고. 같은 항목이 주기(A/M 등)별로 별도 행으로 반환된다.

type KeyStatRow

type KeyStatRow struct {
	ClassName   string `json:"CLASS_NAME"`   // 통계 분류명
	KeyStatName string `json:"KEYSTAT_NAME"` // 지표명
	DataValue   string `json:"DATA_VALUE"`   // 값 (문자열 원본)
	Cycle       string `json:"CYCLE"`        // 수록 시점 — 주기 코드가 아니라 날짜
	UnitName    string `json:"UNIT_NAME"`    // 단위
}

KeyStatRow 는 100대통계지표 응답 행. docs/api/100대통계지표.md 참고.

func (KeyStatRow) Float64

func (r KeyStatRow) Float64() (float64, error)

Float64 는 DataValue 를 float64 로 변환한다.

type KeyStatisticListParams

type KeyStatisticListParams struct {
	Page Page // 제로값은 1~100
}

KeyStatisticListParams 는 KeyStatisticList(100대통계지표) 요청 인자. 서비스별 추가 인자가 없다.

type KeyStatisticListResult

type KeyStatisticListResult struct {
	TotalCount int
	RowCount   int
	Rows       []KeyStatRow
}

KeyStatisticListResult 는 100대통계지표 응답. RowCount 는 이 서비스에만 있는 상위 필드 (이번 응답의 행 수).

type MetaParams

type MetaParams struct {
	Page Page   // 제로값은 1~100
	Name string // 필수 — 데이터명 (예: "경제심리지수")
}

MetaParams 는 StatisticMeta(통계메타DB) 요청 인자.

type MetaResult

type MetaResult struct {
	TotalCount int
	Rows       []MetaRow
}

MetaResult 는 통계메타DB 응답.

type MetaRow

type MetaRow struct {
	Lvl       string `json:"LVL"`         // 트리 깊이 ("1"~"4", 문자열)
	PContCode string `json:"P_CONT_CODE"` // 상위 콘텐츠코드
	ContCode  string `json:"CONT_CODE"`   // 콘텐츠코드
	ContName  string `json:"CONT_NAME"`   // 콘텐츠명
	MetaData  string `json:"META_DATA"`   // 메타데이터 값 (그룹 노드는 null→"")
}

MetaRow 는 통계메타DB 응답 행. docs/api/통계메타DB.md 참고. 트리 구조이며 말단 노드의 MetaData 에 값이 들어 있다.

type Option

type Option func(*clientOptions)

Option 은 functional option.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL 은 API 베이스 URL 을 지정한다 (테스트/프록시용).

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient 는 사용자 정의 *http.Client 를 주입한다.

func WithLanguage

func WithLanguage(lang string) Option

WithLanguage 는 언어구분을 지정한다 ("kr" 또는 "en", 기본 "kr").

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout 은 HTTP 타임아웃을 지정한다 (기본 30s). WithHTTPClient 지정 시 무시된다.

type Page

type Page struct {
	Start int
	End   int
}

Page 는 요청시작건수/요청종료건수 (건수 기반, 1부터). 제로값은 1~100. 지정할 때는 Start/End 를 둘 다 지정한다 (한쪽만 지정하면 그대로 전달되어 ECOS 가 거부한다).

type SearchParams

type SearchParams struct {
	Page      Page   // 제로값은 1~100
	StatCode  string // 필수 — 통계표코드 (예: "722Y001")
	Cycle     Cycle  // 필수 — 주기
	Start     string // 필수 — 검색시작일자 (주기별 날짜 형식)
	End       string // 필수 — 검색종료일자
	ItemCode1 string // 선택 — 통계항목코드1
	ItemCode2 string // 선택
	ItemCode3 string // 선택
	ItemCode4 string // 선택
}

SearchParams 는 StatisticSearch(통계조회) 요청 인자. 항목코드 1~4 는 선택이며, 모두 생략하면 전체 항목이 반환된다 (응답이 매우 커질 수 있음 — docs/api/통계조회.md 참고).

type SearchResult

type SearchResult struct {
	TotalCount int
	Rows       []SearchRow
}

SearchResult 는 통계조회 응답.

type SearchRow

type SearchRow struct {
	StatCode  string `json:"STAT_CODE"`  // 통계표코드
	StatName  string `json:"STAT_NAME"`  // 통계명
	ItemCode1 string `json:"ITEM_CODE1"` // 통계항목코드1
	ItemName1 string `json:"ITEM_NAME1"`
	ItemCode2 string `json:"ITEM_CODE2"` // null → ""
	ItemName2 string `json:"ITEM_NAME2"`
	ItemCode3 string `json:"ITEM_CODE3"`
	ItemName3 string `json:"ITEM_NAME3"`
	ItemCode4 string `json:"ITEM_CODE4"`
	ItemName4 string `json:"ITEM_NAME4"`
	UnitName  string `json:"UNIT_NAME"`  // 단위
	Weight    string `json:"WGT"`        // 가중치 (없으면 null→"")
	Time      string `json:"TIME"`       // 시점 (주기별 날짜 형식)
	DataValue string `json:"DATA_VALUE"` // 값 (문자열 원본)
}

SearchRow 는 통계조회 응답 행. docs/api/통계조회.md 참고.

func (SearchRow) Float64

func (r SearchRow) Float64() (float64, error)

Float64 는 DataValue 를 float64 로 변환한다.

type TableListParams

type TableListParams struct {
	Page     Page   // 제로값은 1~100
	StatCode string // 선택 — 지정 시 해당 통계표만
}

TableListParams 는 StatisticTableList(통계표목록) 요청 인자.

type TableListResult

type TableListResult struct {
	TotalCount int
	Rows       []TableRow
}

TableListResult 는 통계표목록 응답.

type TableRow

type TableRow struct {
	PStatCode string `json:"P_STAT_CODE"` // 상위 통계표코드 (최상위는 "*")
	StatCode  string `json:"STAT_CODE"`   // 통계표코드
	StatName  string `json:"STAT_NAME"`   // 통계명
	Cycle     string `json:"CYCLE"`       // 주기 (그룹 노드는 null→"")
	SrchYN    string `json:"SRCH_YN"`     // "Y"면 StatisticSearch 조회 가능
	OrgName   string `json:"ORG_NAME"`    // 출처 (대부분 null→"")
}

TableRow 는 통계표목록 응답 행. docs/api/통계표목록.md 참고.

type WordParams

type WordParams struct {
	Page Page   // 제로값은 1~100
	Word string // 필수 — 검색할 용어
}

WordParams 는 StatisticWord(통계용어사전) 요청 인자.

type WordResult

type WordResult struct {
	TotalCount int
	Rows       []WordRow
}

WordResult 는 통계용어사전 응답.

type WordRow

type WordRow struct {
	Word    string `json:"WORD"`    // 용어
	Content string `json:"CONTENT"` // 용어 설명
}

WordRow 는 통계용어사전 응답 행. docs/api/통계용어사전.md 참고.