무료 공공 API로 거시경제금융 대시보드 만들기

FRED API 사용법을 찾다가 결국 키 없이 CSV 한 줄로 받았다. 돈 안 내고 경제 대시보드를 채워보니 오래 붙잡힌 건 수집보다 빈칸을 어떻게 표시하느냐였다.

한 달에 한 번 열어보는 경제 대시보드를 클로드코드(앤트로픽이 만든 AI 코딩 도구)한테 만들게 했다. 화면은 두 장이다. 하나는 전 세계 ETF(거래소에서 주식처럼 사고파는 펀드)로 돈이 어디에 들어가고 어디서 빠졌는지 분류별 유입·유출 크기를 색 진하기로 칠한 표(히트맵)이고, 다른 하나는 한국 안에서 외국인·기관·개인·연금 돈이 어느 자산으로 흘렀는지 잇는 흐름도다.

API는 프로그램이 다른 기관 서버에 "이 숫자 주세요" 하고 요청하는 정해진 창구다. 사람이 웹페이지 들어가서 표를 복사하는 일을 코드가 대신 하는 거라고 보면 된다.

조건은 유료 단말(블룸버그처럼 월 구독료를 내는 데이터 터미널)은 안 쓰고 새 API 키도 늘리지 않는 것이었다. 수집을 언제 돌리고 어디로 보내는지는 매크로 지표 자동 수집 글에서 이미 풀었으니까 여기선 칸마다 어느 무료 창구에서 어떤 주소로 받았는지, 못 구한 칸을 어떻게 처리했는지만 적는다.

1. 칸부터 그려놓고 공짜 출처를 붙였다

데이터부터 모으지 않고 화면을 먼저 그렸다. 목업(숫자 없이 모양만 잡은 시안)을 세 번 고쳐서 내가 모양을 확정했고 그다음에 칸마다 "이건 어디서 공짜로 나오나"를 붙여 나갔다. 글로벌 쪽은 미국 주식·선진국·신흥국·채권·MMF(머니마켓펀드, 초단기 현금성 펀드)·금·크립토·달러까지 15분류였다. 한국 쪽은 주체 넷(외국인·기관·개인·연금)과 자산 여섯(국내주식·국내채권·해외자산·부동산·크립토·예탁금)을 잇는 구조였고.

출처 붙이기는 클로드코드가 했다. 나는 클로드코드에게 칸마다 무료 출처 후보를 찾아오게 하고 안 나오는 칸은 안 나온다고 표시해서 가져오게 했다. 공공 데이터로 질문 하나를 확인하는 건 대미투자 글에서 한 번 해봤는데, 이번엔 질문 하나가 아니라 칸 수십 개를 매달 채워야 했다. 규모가 달라지니 문제도 달라지더라.

▲ FRED, 한국은행 ECOS, 공공데이터포털, yfinance, ICI 다섯 데이터 창구의 받는 방법과 지연을 비교한 표 (자체 제작 이미지)

2. FRED API 사용법, 나는 키 없이 CSV로 받았다

FRED 정식 API는 계정을 만들고 키를 받아야 쓸 수 있지만 그래프 화면의 CSV(쉼표로 칸을 나눈 표 파일) 다운로드 주소는 키 없이 표를 내려준다. (fred.stlouisfed.org) FRED는 미국 세인트루이스 연방준비은행이 운영하는 경제 데이터 저장소다. 금리·통화량·달러지수 같은 시계열이 수십만 개 올라와 있다. (fred.stlouisfed.org)

그 주소엔 시리즈 ID(FRED가 지표마다 붙인 고유 코드, 예: BAMLH0A0HYM2)랑 시작일만 넣으면 된다.

https://fred.stlouisfed.org/graph/fredgraph.csv?id=BAMLH0A0HYM2&cosd=2024-01-01

클로드코드가 이 길을 골랐다. 새 키를 안 늘린다는 조건과 딱 맞았으니까. 다만 이 주소는 내가 그래프 화면의 다운로드 버튼에서 따온 거다. 호출을 많이 돌릴 사람은 키를 받고 정식 API로 가는 게 맞을 거다. 키는 FRED 계정을 만든 뒤 API 키 안내 페이지에서 신청하면 받는다. 정식 API는 관측값을 주는 주소에 시리즈 ID와 발급받은 키, 응답 형식을 붙여서 부른다. (fred.stlouisfed.org)

api.stlouisfed.org/fred/series/observations?series_id=BAMLH0A0HYM2&api_key=발급받은키&file_type=json

응답 형식을 json으로 주면 observations라는 목록에 날짜(date)와 값(value)이 한 쌍씩 담겨 온다. (fred.stlouisfed.org) 나는 한 달에 몇 번 부르는 수준이라 CSV 주소로 충분했다.

받아온 시리즈는 다섯 개다. 미국 하이일드(신용등급이 낮은 회사채) 스프레드(BAMLH0A0HYM2)·투자등급(신용등급이 높은 회사채) 스프레드(BAMLC0A0CM)·10년 물가연동국채(물가가 오른 만큼 원금이 불어나는 국채) 실질금리(DFII10)·미국 M2 통화량(시중에 풀린 돈의 양을 재는 지표, M2SL)·광의 달러지수(주요 교역국 통화 전반에 견준 달러 가치, DTWEXBGS)를 받았다. 스프레드는 회사채 금리가 국채보다 얼마나 더 높은지를 잰 값이다. 이게 벌어지면 시장이 기업 부도를 더 걱정한다는 뜻이고. (fred.stlouisfed.org)

신용 위험 칸은 미국 하이일드 스프레드로 채우고 한국 위험이 아니라 글로벌 신용 분위기를 본다는 메모를 숫자 옆에 달았다. 칸 이름과 실제 내용이 어긋나면 나중에 내가 헷갈릴 게 뻔해서..

FRED CSV는 관측이 없는 날에 숫자 대신 점(.) 하나를 찍어둔다. 이걸 그대로 숫자로 바꾸면 에러가 나니까 읽을 때 점은 버리고 넘어가게 했다.

3. 한국 기관은 인증도 응답 모양도 제각각이었다

FRED는 키도 없고 CSV라 편했는데, 한국 쪽은 기관마다 문법이 다 달랐다.

한국은행 ECOS는 키를 받아야 하고 숫자 하나 부르려면 통계표 코드와 항목 코드를 짝으로 넣어야 한다. (ecos.bok.or.kr) 원/달러 매매기준율(은행이 환율을 매길 때 기준으로 삼는 값)과 국고채 만기별 금리를 여기서 받는다. 원/달러를 부르는 주소는 이런 모양이다. 731Y001이 통계표 코드, D가 일별, 맨 끝 0000001이 원/달러 항목 코드다.

ecos.bok.or.kr/api/StatisticSearch/발급받은키/json/kr/1/100/731Y001/D/20240101/20241231/0000001

코드표를 한 번 찾아두면 그다음부턴 편하더라.

공공데이터포털은 서비스마다 활용신청을 하고 serviceKey를 받는 구조다. 나는 금융투자협회 통계를 쓰는데, 내가 부를 때는 숫자가 며칠씩 늦게 올라오더라. 오늘 날짜로 부르면 빈 응답이 오는 거다. 그래서 수집기가 하루씩 뒤로 물러나면서 값이 나올 때까지 다시 묻게 했다.

신용융자 잔고(증권사에서 돈을 빌려 주식을 산 금액)를 받던 같은 서비스와 같은 키 안에 증시자금추이라는 다른 창구가 있었는데 거기에 투자자예탁금(주식을 사려고 증권 계좌에 넣어둔 돈)·반대매매(신용으로 산 주식의 담보가 모자랄 때 증권사가 강제로 파는 금액) 실측·위탁매매 미수금(주식을 사고 아직 치르지 않은 대금)이 다 들어 있었다. 첫 호출에서 예탁금 잔고는 120.08조, 반대매매는 가장 최근 영업일 하루치가 257억, 미수금 잔고는 1.26조로 나왔다.

외국인 채권 순투자는 출처를 한 번 바꿨다. 처음엔 ECOS의 국제수지(나라 안팎으로 오간 돈의 기록) 표로 채웠는데(키 추가 없음) 내가 받을 땐 이 숫자가 꽤 늦게 올라왔다. 내가 찾아볼 땐 한국은행이 내는 「국제금융·외환시장 동향」 보도자료 쪽에 같은 항목이 먼저 나와 있었다. 다만 이건 API가 아니라 PDF다. 클로드코드가 새 보도자료가 올라오는 걸 감지하고 PDF를 읽어 숫자를 뽑고 기존 값과 맞춰보고 병합하는 단계를 짰다. 나는 이 교체안에 오케이만 했다. 지난 달 값도 PDF로 다시 채웠다. 국제수지 표는 버리지 않고 남겨뒀다. PDF 파싱이 실패하면 대신 쓰고 평소엔 PDF 숫자가 맞는지 대조하는 용도로.

기관이 늘수록 응답 모양이 다 다르니까, 클로드코드가 수집기마다 돌려주는 응답 모양을 하나로 맞추게 했다. 맞춘 응답엔 값, 그 값의 날짜, 출처 메모, 실패했을 때의 실패 사유 네 칸이 들어간다. 한 기관이 죽어도 전체 프로그램은 안 멈추고 "어디서 왜 못 받았다"를 담아서 돌려준다. 이걸 맞춰두니 뒤쪽 그림 그리는 코드는 데이터가 FRED에서 왔는지 PDF에서 왔는지 신경 쓸 필요가 없어졌다.

4. 과거 기록을 안 주는 데이터는 매달 직접 쌓았다

글로벌 히트맵의 핵심인 ETF 순유입은 무료 출처가 과거 기록을 주지 않았다. 한 달 동안 ETF로 들어온 돈은 발행주식수 변화에 기준가(NAV, 펀드 한 주가 실제로 담고 있는 자산 가치)를 곱하면 나온다. 무료로 이 숫자를 주는 곳이 yfinance였다. 야후 파이낸스 숫자를 받아오는 파이썬 라이브러리인데, 야후 공식 API가 아니라 개인 개발자가 만든 비공식 도구다. (github.com)

그런데 yfinance는 오늘 기준 스냅샷만 줬다. 과거 발행주식수 이력을 달라고 하니 추적 대상으로 골라 둔 ETF가 전부 빈값으로 돌아왔다.

그래서 매달 1일에 스냅샷을 찍어 쌓기로 했다. 첫 달은 저장만 하고, 두 번째 달부터 차이를 계산한다. 그럼 그 전 칸은? ICI(미국 자산운용협회)가 내는 월간 펀드 자금 통계로 상단 분류만 채우고 "백필"(지난 칸을 나중에 다른 자료로 메워 넣었다는 뜻)이라고 라벨을 붙였다. (ici.org) 내 스냅샷이 쌓이면 그 칸부터 교체된다. ICI 공식치도 내가 받을 땐 꽤 늦게 올라왔다. 그래서 기준월 칸에는 주간 수치를 합산한 추정을 먼저 넣고 공식치가 나오면 자동으로 바뀌게 해뒀다.

스냅샷도 다 깨끗하진 않았다. 일부 종목은 발행주식수 칸 자체가 비어 있었다. 클로드코드가 총자산 변화에서 가격 변동분을 빼는 계산으로 대신했는데, 수학적으로는 같은 값이 나온다. 그래도 계산 경로가 다르니 그 칸엔 * 표시를 붙였다.

크립토는 더 번거로웠다. 비트코인 현물 ETF 자금 흐름을 날마다 정리해 올리는 Farside라는 사이트가 있는데 (farside.co.uk), 봇 차단이 걸려 있어서 자동 수집이 안 됐다. 결국 브라우저로 한 번 열어 지난 기록을 받아두고 출처를 적었다. 그 뒤로는 매달 쌓는 쪽으로 넘겼다.

5. 못 채운 칸에 0 대신 이유를 남겼다

칸을 다 채우진 못했다. 그건 처음부터 예상했다. 진짜로는 빈칸을 어떻게 보여줄지를 정해야 했다.

데이터로 못 잇는 칸은 그리지 않는다. 0으로 채우지도 않는다. 빈칸에 0을 넣는 순간 "모른다"가 "돈이 안 움직였다"라는 주장으로 바뀐다. 흐름도에서 0짜리 선은 그냥 안 보이는 선이라 독자가 차이를 알 방법이 없다.

그래서 칸마다 상태를 적었다. 한국 흐름도에서 개인→크립토 선은 김치프리미엄(국내 크립토 가격이 해외보다 비싼 정도)과 거래대금으로 방향까진 짐작되는데 규모를 잡을 수가 없었다. 이 선은 빼고 "규모 추정 불가로 제외"라고 사유를 남겼다. 개인→부동산 선은 주택담보대출 증감으로 방향만 보는 거라 그 선에 ※간접 표시를 달았다. 개인과 기관이 해외자산을 산 금액은 주체별로 쪼개지지 않아서 나는 그 둘을 "국내 주체 통합" 한 줄로 묶었다. 국제수지처럼 늦게 나오는 숫자엔 몇 월 기준인지 지연 라벨을 붙였고.

흐름도 아래엔 주의문도 하나 상시로 달았다. 주의문은 선들을 다 더해도 회계상 딱 맞아떨어지는 합계가 아니라고 알린다. 출처가 제각각이라 맞을 수가 없다. 그래서 선 하나하나는 돈이 어느 쪽으로 얼마쯤 갔는지만 읽고, 나라 밖과 오간 돈 전체 크기는 국제수지 통계로 따로 확인하는 식으로 본다.

ETF 쪽 이례 표시(평소보다 크게 튄 달에 붙이는 표시)도 같은 원칙이다. 12개월치가 쌓여야 평균에서 얼마나 벗어났는지 말할 수 있는데, 그 전까지는 "축적 중 (N/12개월)"이라고만 띄운다. 3개월치로 이례라고 표시하는 건 가짜 판정이니까.

yfinance 원자료를 표째로 다시 퍼뜨려도 되는지 이용 조건상 분명하지 않아서 나는 밖에 낼 때 직접 계산한 수치와 직접 그린 차트만 쓰고 출처를 같이 적는다.

▲ 못 채운 칸에 붙인 백필, 주간합산 추정, 별표, 간접, 제외와 사유, 축적 중 라벨 여섯 종의 뜻을 정리한 카드 (자체 제작 이미지)

6. 에러 없이 틀린 숫자는 따로 띄운 검증자가 잡았다

빈칸은 눈에 보이니까 차라리 낫다. API가 정상 응답을 주고 코드도 안 죽고 숫자도 그럴듯한데 틀린 경우가 더 무서웠다.

다 만들고 자체 점검은 통과했다. 그다음 만든 쪽 맥락이 없는 검증 에이전트(이하 검증자)를 새로 띄워 채점시켰다(왜 따로 띄우는지는 검증 게이트 글에 적었다). 거기서 둘이 나왔다.

첫째는 환율이었다. 외국인 채권 순투자는 달러 단위라 원화로 바꿔야 한다. 그런데 코드는 과거 몇 달치를 조회하는 그 달의 환율 하나로 전부 환산하고 있었다. 그러면 같은 원자료도 언제 조회하느냐에 따라 값이 달라진다. 각 데이터 월의 월말 환율을 따로 쓰게 고쳤더니 채권 선은 9.9조에서 9.6조로, 해외자산 선은 9.6조에서 9.4조로 바뀌었다.

둘째는 실패 기록이었다. 수집이 실패한 칸엔 "이 칸 못 받음"이라는 기록을 남기는데, 다음 실행에서 값을 제대로 받아와도 그 기록이 안 지워지고 남아 있었다. 화면엔 숫자가 멀쩡히 찍히는데 기록상으론 그 칸이 여전히 빈칸인 셈이다. 나중에 언제 뭐가 빠졌는지 거슬러 볼 때 그 기록을 믿을 수 없게 된다. 값을 받는 데 성공하면 그 칸의 실패 기록을 지우게 고쳤다.

같은 방식이 이보다 앞서 한 번 통한 적이 있다. 대시보드를 만들기 전, 7월에 예탁금·반대매매 실측을 주간·월간 보고에 붙이던 작업에서였다. 반대매매는 매일 생기는 흐름인데 코드가 잔고처럼 월말 하루끼리 비교해서 +350%를 찍었고 그때 띄운 검증자가 이걸 짚었다. 클로드코드가 검증자 권고대로 월평균 비교로 고치자 전월 일평균 348억에서 당월 일평균 572억으로 64.5% 늘어난 걸로 바뀌더라. 그 달 하루 최고치 1,698억은 따로 옆에 적게 했다.

이번 둘도 앞선 하나도 API 쪽 잘못은 없었다. 받아온 숫자를 단위 성격(흐름인가 잔고인가)과 환율 기준을 놓친 채 이어 붙이고, 실패 기록을 제때 안 지운 데서 생겼다. 그래서 방어도 수집기가 아니라 숫자 옆에 붙는 날짜·출처·상태 라벨에 걸었다.

▲ 반대매매, 외국인 채권, 해외자산의 틀린 숫자와 고친 숫자를 전후로 비교한 카드 (자체 제작 이미지)

7. 유료 데이터 없이 크립토 선 하나만 빼고 다 이었다

글로벌 15분류 히트맵은 ETF 스냅샷과 ICI 백필로 채웠고 한국 흐름도는 크립토 선 하나를 빼고 다 이었다. 그중 부동산은 간접 표시고, 해외자산은 주체 통합이다. 지금까지 유료 데이터로 넘어간 칸은 없다. 이 대시보드 숫자를 받아 보고서 글까지 기계한테 넘긴 얘기는 월간 보고서 집필 자동화 글에 있고 숫자를 색으로 줄였다가 생긴 일은 신호등 3색 글에 있다.

해보고 나니 무료로 되는 범위는 생각보다 넓었다. 대신 공짜 데이터는 늦게 오고 이력을 안 주고 가끔 칸 자체가 비어 있다. 그 사정을 숫자 옆에 같이 적어두는 데 품이 제일 많이 들었다.

비슷한 대시보드를 다시 만든다면 나는 화면 칸부터 그리고 칸마다 무료 창구를 붙이는 순서를 그대로 택하겠다. 과거 이력을 안 주는 데이터는 가동 첫 달부터 직접 쌓기 시작해야 한다. 못 구한 칸은 0으로 메우지 말고 사유를 적어두는 쪽이 나중에 덜 헷갈리더라.

3줄 요약

FRED는 정식 API 키 없이도 그래프 CSV 주소로 받을 수 있었고 한국 쪽은 ECOS·공공데이터포털·한국은행 PDF를 값·날짜·출처·실패사유 네 칸으로 맞춰 한 창구로 모았다.
과거 이력을 안 주는 ETF 데이터는 매달 직접 쌓았고 그 전 칸은 백필·추정·* 라벨을 달아 채웠다.
못 채운 칸은 0 대신 사유를 남겼다. 에러 없이 틀린 숫자는 따로 띄운 검증자가 잡았는데 이번엔 환율과 남아 있던 실패 기록 둘이었고 앞선 7월 작업에선 반대매매가 걸렸다.

이 글은 정보 제공이 목적이고, 작성 시점 기준이다. 내용은 이후 바뀔 수 있으니 중요한 판단 전에는 공식 자료를 한 번 확인하는 게 좋다. 특정 선택을 권유하거나 결과를 보장하지 않는다.

참고한 공식 자료

FRED 메인: fred.stlouisfed.org
FRED API 키 안내: FRED API Keys
ICE BofA 미국 하이일드 스프레드 시리즈: BAMLH0A0HYM2
한국은행 경제통계시스템 Open API: ecos.bok.or.kr/api
yfinance(비공식 파이썬 라이브러리): GitHub ranaroussi/yfinance
ICI 펀드 통계: ici.org/research/stats
비트코인 현물 ETF 흐름: Farside Investors