미국 연준(Fed)의 금리 결정, VIX 공포지수 급등, 장단기 금리차 역전 같은 뉴스를 접할 때마다 이 데이터를 직접 가져와서 차트로 그릴 수 없을까 하는 생각을 해본 적이 있을 것이다. 월스트리트의 기관 투자자부터 한국의 개인 투자자까지, 미국 경제 데이터의 1차 출처로 사용하는 곳이 바로 FRED(Federal Reserve Economic Data) 데이터베이스다.
FRED는 세인트루이스 연방준비은행이 1991년부터 운영해온 경제 데이터 플랫폼으로, 118개 이상의 공공·민간 기관에서 수집한 84만 개 이상의 시계열 데이터를 무료로 제공한다. 더 중요한 것은 이 방대한 데이터를 프로그래밍 방식으로 자동 수집할 수 있는 REST API를 완전 무료로 개방하고 있다는 점이다.
이 글에서는 FRED API의 가격 정책과 제한 사항, 실제 API 호출 방법, 투자에 활용 가능한 핵심 시리즈 ID 목록, 그리고 Next.js나 Python 환경에서의 실전 구현까지 다룬다. 금융 대시보드를 직접 만들거나, 투자 판단에 필요한 매크로 데이터를 자동화하고 싶은 개발자와 투자자 모두에게 실용적인 내용이 될 것이다.
FRED API 가격 정책과 제한 사항
FRED API의 가장 큰 장점은 완전 무료라는 것이다. 유료 플랜이나 프리미엄 티어 자체가 존재하지 않는다. 세인트루이스 연준이 공공 서비스 차원에서 운영하기 때문에, API 키만 발급받으면 누구나 동일한 조건으로 84만 개 이상의 시계열 데이터에 접근할 수 있다.
다만 무제한은 아니다. FRED API에는 분당 120회 요청(120 requests/minute) 이라는 Rate Limit가 적용된다. 이 한도를 초과하면 HTTP 429 상태 코드가 반환되며, 약 20초 정도 대기 후 재시도해야 한다. 일반적인 대시보드나 분석 용도에서는 충분한 수치다. 예를 들어 20개 지표를 1분 간격으로 갱신해도 분당 20회에 불과하므로 한도의 17% 수준이다.
| 항목 | 내용 |
|---|---|
| 가격 | 완전 무료 (유료 플랜 없음) |
| API 키 발급 | 무료 회원가입 후 즉시 발급 |
| Rate Limit | 분당 120회 요청 |
| 데이터 시리즈 수 | 84만 개 이상 |
| 데이터 소스 수 | 118개 이상 (공공+민간) |
| 응답 포맷 | XML, JSON, XLSX, CSV |
| 최대 반환 건수 | 요청당 100,000건 |
| 인증 방식 | API Key (32자 영소문자+숫자) |
| HTTPS 필수 | 필수 (HTTP 미지원) |
| 상업적 사용 | 조건부 허용 (출처 표기 필수) |
FRED API는 분당 120회 제한만 지키면 일일 총 요청 수에는 별도 한도가 없다. 하루 종일 10초에 한 번씩 호출해도 이론상 일 8,640회 호출이 가능하며, 이는 대부분의 개인 프로젝트에서 넉넉한 수준이다.
API 키 발급 과정도 간단하다. FRED 공식 사이트에서 무료 계정을 생성한 뒤, API Keys 메뉴에서 신청하면 32자리 영소문자+숫자 조합의 키가 즉시 발급된다. 별도의 심사나 대기 기간이 없다.
상업적 사용에 대한 제한도 비교적 유연하다. 단, 반드시 다음 문구를 애플리케이션에 표시해야 한다는 조건이 있다: This product uses the FRED API but is not endorsed or certified by the Federal Reserve Bank of St. Louis. 이 문구 없이 상업적으로 활용하면 이용약관 위반이다.
FRED에 포함된 일부 시리즈는 제3자 저작권이 적용된다. 시리즈 설명(Notes)에 Copyright라는 단어가 포함된 데이터는 개인 사용 외 목적으로 활용하기 전에 반드시 원저작권자의 허가를 받아야 한다. 예를 들어 S&P 500 지수 데이터(SP500)는 S&P Dow Jones Indices LLC의 저작권이 적용된다.
FRED API 핵심 엔드포인트와 호출 방법
FRED API는 REST 아키텍처 기반으로, HTTPS GET 요청을 통해 데이터를 받는다. 모든 요청의 Base URL은 https://api.stlouisfed.org/fred/ 이며, 뒤에 엔드포인트 경로와 쿼리 파라미터를 붙이는 구조다.
주요 엔드포인트 구조
FRED API는 크게 5가지 도메인으로 나뉜다.
| 도메인 | 주요 엔드포인트 | 용도 |
|---|---|---|
| Categories | fred/category, fred/category/series | 카테고리별 데이터 분류 탐색 |
| Releases | fred/releases, fred/release/dates | 경제 지표 발표 일정 조회 |
| Series | fred/series, fred/series/observations | 시계열 데이터 조회 (핵심) |
| Sources | fred/sources, fred/source/releases | 데이터 제공 기관 조회 |
| Tags | fred/tags, fred/tags/series | 태그 기반 시리즈 검색 |
이 중 투자와 대시보드 구축에 가장 많이 쓰이는 엔드포인트는 단연 fred/series/observations다. 이 엔드포인트 하나로 VIX, 금리, 통화량, 연준 대차대조표 등 모든 시계열 데이터의 실제 값(observations)을 가져올 수 있다.
fred/series/observations 호출 예시
가장 기본적인 호출 형태는 다음과 같다.
https://api.stlouisfed.org/fred/series/observations?series_id=VIXCLS&api_key=YOUR_KEY&file_type=json이 요청은 VIX 지수(VIXCLS)의 전체 히스토리를 JSON 형태로 반환한다. 응답 구조의 핵심은 observations 배열이며, 각 항목에 date와 value 필드가 포함된다. realtime_start, realtime_end는 현재 날짜, count는 전체 데이터 건수를 나타낸다.
핵심 파라미터 상세
| 파라미터 | 필수 | 설명 | 예시 |
|---|---|---|---|
| series_id | 필수 | 데이터 시리즈 고유 ID | VIXCLS, T10Y2Y, WALCL |
| api_key | 필수 | 32자리 API 키 | abcdef... |
| file_type | 선택 | 응답 포맷 (기본값 xml) | json, xml, xlsx, csv |
| observation_start | 선택 | 조회 시작일 | 2024-01-01 |
| observation_end | 선택 | 조회 종료일 | 2026-03-16 |
| frequency | 선택 | 빈도 변환 | d(일), w(주), m(월), q(분기), a(연) |
| units | 선택 | 데이터 변환 | lin(원본), pch(전기비%), pc1(전년비%) |
| aggregation_method | 선택 | 집계 방식 | avg(평균), sum(합계), eop(기말값) |
| sort_order | 선택 | 정렬 순서 | asc(오름차순), desc(내림차순) |
| limit | 선택 | 최대 반환 건수 (기본 100,000) | 250 |
units 파라미터를 활용하면 별도 계산 없이 전기 대비 변화율(pch), 전년 동기 대비 변화율(pc1), 자연로그(log) 등을 서버 측에서 자동 변환해 받을 수 있다. 예를 들어 M2 통화량의 전년비 증가율을 한 번의 호출로 구할 수 있다.
fred/series/search - 시리즈 검색
원하는 데이터의 시리즈 ID를 모를 때는 검색 엔드포인트를 활용한다.
https://api.stlouisfed.org/fred/series/search?search_text=unemployment+rate&api_key=YOUR_KEY&file_type=json이 요청은 unemployment rate 키워드와 관련된 시리즈 목록을 인기도순(popularity)으로 반환한다. 시리즈 ID, 제목, 빈도, 단위, 계절 조정 여부 등 메타데이터가 포함되어 있어 정확한 시리즈를 특정하는 데 유용하다.
FRED에는 같은 경제 지표라도 빈도(일간/주간/월간)나 계절 조정 여부에 따라 여러 시리즈가 존재한다. 예를 들어 소비자물가지수(CPI)는 CPIAUCSL(계절 조정), CPIAUCNS(비계절 조정) 등으로 나뉜다. 반드시 시리즈 설명을 확인하고 목적에 맞는 것을 선택해야 한다.
투자자를 위한 핵심 시리즈 ID 레퍼런스
FRED의 84만 개 시리즈 중 투자 판단에 실질적으로 쓰이는 핵심 지표는 30 - 50개 내외다. 아래는 카테고리별로 정리한 투자 필수 시리즈 ID 목록이다.
시장 심리 및 변동성
| 시리즈 ID | 지표명 | 빈도 | 투자 활용 |
|---|---|---|---|
| VIXCLS | VIX 공포지수 | 일간 | 20 이하 안정, 30 이상 경계, 40 이상 위기 수준 |
| T10Y2Y | 장단기 금리차 (10Y-2Y) | 일간 | 음수(역전) 시 경기침체 선행 신호 |
| BAMLH0A0HYM2 | 하이일드 스프레드 | 일간 | 4 - 6% 주의, 8% 이상 신용경색 수준 |
| STLFSI4 | 금융스트레스지수 | 주간 | 0 이상이면 평균 이상 스트레스 |
금리 및 채권
| 시리즈 ID | 지표명 | 빈도 | 투자 활용 |
|---|---|---|---|
| DGS10 | 미국 10년물 국채금리 | 일간 | 주식 밸류에이션 할인율 기준 |
| DGS2 | 미국 2년물 국채금리 | 일간 | 연준 정책금리 기대 반영 |
| DFF | 연방기금 실효금리 | 일간 | 연준의 실제 정책금리 |
| SOFR | SOFR 금리 | 일간 | 담보부 초단기 금리 |
| EFFR | EFFR 금리 | 일간 | 무담보 초단기 금리 |
| IORB | IORB 금리 | 일간 | 연준이 초과준비금에 지급하는 이율 |
유동성 지표
| 시리즈 ID | 지표명 | 빈도 | 투자 활용 |
|---|---|---|---|
| WALCL | 연준 총자산 (대차대조표) | 주간 | QE/QT 진행 상황 파악 |
| WRESBAL | 연준 지급준비금 | 주간 | 은행 시스템 유동성 수준 |
| RRPONTSYD | 역레포(RRP) 잔액 | 일간 | 초과 유동성 흡수량 |
| WTREGEN | TGA (재무부 일반계정) | 주간 | 정부 지출에 따른 유동성 변동 |
| WRMFNS | MMF 총잔액 | 주간 | 대기 자금 규모 |
| M2SL | M2 통화량 | 월간 | 시중 유동성 총규모 |
고용 및 거시경제
| 시리즈 ID | 지표명 | 빈도 | 투자 활용 |
|---|---|---|---|
| UNRATE | 실업률 | 월간 | 연준 금리 결정 핵심 변수 |
| ICSA | 신규 실업수당 청구 | 주간 | 고용시장 실시간 체크 |
| CPIAUCSL | 소비자물가지수 (CPI) | 월간 | 인플레이션 핵심 지표 |
| PCEPI | PCE 물가지수 | 월간 | 연준 선호 인플레이션 지표 |
| GDP | 명목 GDP | 분기 | 경제 성장 지표 |
| DCOILWTICO | WTI 원유가격 | 일간 | 인플레이션 선행 변수 |
금융 대시보드를 만들 때 시리즈 ID의 빈도(일간/주간/월간)를 반드시 확인해야 한다. 일간 데이터인 VIX(VIXCLS)와 주간 데이터인 연준 총자산(WALCL)을 동일한 갱신 주기로 호출하면 주간 데이터 쪽에서 불필요한 API 호출이 발생한다. WALCL은 매주 수요일, RRPONTSYD는 영업일 기준 매일 갱신되는 식으로 각 시리즈마다 업데이트 주기가 다르다.
FRED API vs 다른 금융 데이터 API 비교
FRED API는 매크로 경제 데이터에 특화되어 있다. 개별 종목 주가나 실시간 호가 데이터가 필요하다면 다른 API를 함께 사용해야 한다.
| 비교 항목 | FRED API | Yahoo Finance | Alpha Vantage | Trading Economics |
|---|---|---|---|---|
| 가격 | 완전 무료 | 비공식 무료 (불안정) | 무료 25회/일, 유료 월 50달러 이상 | 무료 제한적, 유료 월 30달러 이상 |
| 데이터 유형 | 매크로 경제지표 전문 | 주가, ETF, 환율, 원자재 | 주가, 환율, 암호화폐, 기술지표 | 매크로 + 시장 데이터 |
| 시리즈 수 | 84만 개 이상 | 수만 종목 (추정) | 수천 종목 | 30만 개 이상 |
| 업데이트 빈도 | 일간 - 연간 (실시간 아님) | 준실시간 (15분 지연) | 준실시간 (무료 15분 지연) | 실시간 + 히스토리 |
| API 안정성 | 매우 높음 (공식 API) | 불안정 (비공식, 언제든 차단 가능) | 안정적 (공식 API) | 안정적 (공식 API) |
| Rate Limit | 분당 120회 | 비공개 (과다 호출 시 차단) | 무료 일 25회 | 플랜별 상이 |
| 출처 신뢰도 | 최상 (미국 연방준비은행) | 보통 (비공식 스크래핑) | 높음 (공식 제공) | 높음 (공식 제공) |
실제로 assetx2-dashboard 같은 금융 대시보드 프로젝트에서는 FRED API로 매크로 지표(VIX, 금리차, 연준 대차대조표, RRP, SOFR 등 18종 이상)를 수집하고, Yahoo Finance API로 개별 종목과 ETF 가격(S&P500, 비트코인, 금, 환율 등 15종 이상)을 병행 수집하는 방식이 일반적이다.
Yahoo Finance는 공식 API가 아닌 비공식 엔드포인트를 활용하는 방식이라, 사전 예고 없이 구조가 변경되거나 차단될 수 있다. 안정적인 서비스 운영이 필요하다면 FRED API처럼 공식 제공되는 API를 우선 고려하고, Yahoo Finance는 보조 수단으로 활용하는 것이 바람직하다.
Python과 JavaScript에서의 실전 구현
Python 환경 (fredapi 패키지)
Python에서 FRED 데이터를 가져오는 가장 간편한 방법은 fredapi 패키지를 사용하는 것이다.
pip install fredapi
설치 후 3줄이면 VIX 데이터를 Pandas DataFrame으로 받을 수 있다.
from fredapi import Fred
fred = Fred(api_key='YOUR_API_KEY')
vix = fred.get_series('VIXCLS', observation_start='2024-01-01')
여러 시리즈를 한 번에 가져와 DataFrame으로 합치는 패턴도 자주 쓰인다.
import pandas as pd
from fredapi import Fred
fred = Fred(api_key='YOUR_API_KEY')
series_ids = ['VIXCLS', 'T10Y2Y', 'DGS10', 'BAMLH0A0HYM2']
data = {sid: fred.get_series(sid, observation_start='2024-01-01') for sid in series_ids}
df = pd.DataFrame(data)
JavaScript/Next.js 환경 (API Route 프록시 패턴)
Next.js에서는 API Route를 프록시로 활용해 서버 측에서 FRED를 호출하는 패턴이 표준이다. 이렇게 하면 API 키가 브라우저에 노출되지 않는다.
서버 측 API Route 파일(app/api/fred/route.ts)에서 FRED_API_KEY 환경변수를 사용해 https://api.stlouisfed.org/fred/series/observations 엔드포인트를 호출하고, 응답의 observations 배열에서 date와 value를 추출해 정리된 JSON으로 반환한다.
프론트엔드에서는 내부 API 경로(/api/fred?series=VIXCLS)만 호출하면 된다.
Next.js에서 FRED API를 호출할 때는 revalidate 옵션을 활용해 ISR(Incremental Static Regeneration)로 캐싱하는 것이 효율적이다. 예를 들어 next revalidate 값을 3600으로 설정하면, 1시간마다 한 번씩만 실제 FRED 서버를 호출하고 나머지는 캐시된 결과를 반환한다. 일간 데이터는 3,600초(1시간), 주간 데이터는 86,400초(1일) 캐싱이면 충분하다.
API 키 발급부터 첫 호출까지 5단계
실제로 FRED API를 시작하는 과정은 5분이면 끝난다.
1단계 - 계정 생성: FRED 공식 사이트 상단의 Create New Account 버튼을 클릭하고 이메일, 비밀번호를 입력한다. 이메일 인증까지 약 2분 소요된다.
2단계 - API 키 발급: 로그인 후 My Account 메뉴에서 API Keys 섹션으로 이동한다. Request API Key 버튼을 누르면 32자리 영소문자+숫자 조합의 키가 즉시 생성된다.
3단계 - 테스트 호출: 브라우저 주소창에 series_id=GDP, api_key=YOUR_KEY, file_type=json, limit=5, sort_order=desc 파라미터를 포함한 observations 엔드포인트 URL을 입력하면 바로 JSON 응답을 확인할 수 있다.
4단계 - 시리즈 탐색: 원하는 지표를 찾으려면 FRED 웹사이트의 검색창에 키워드를 입력하거나, API의 fred/series/search 엔드포인트를 활용한다. 각 시리즈 페이지 URL의 마지막 부분이 시리즈 ID다.
5단계 - 프로젝트 연동: 환경 변수로 API 키를 저장하고, 앞서 소개한 Python 또는 JavaScript 코드를 적용하면 된다.
API 키는 절대로 프론트엔드 코드나 GitHub 공개 저장소에 하드코딩하지 않아야 한다. Vercel의 경우 프로젝트 설정의 Environment Variables에, 로컬 개발 환경에서는 .env.local 파일에 저장하는 것이 기본이다.
FRED 데이터 활용의 실전 팁과 주의점
FRED API를 실무에 적용할 때 자주 마주치는 이슈와 해결 방법을 정리한다.
결측값 처리 문제가 가장 흔하다. FRED의 일간 시리즈에서 주말이나 공휴일에는 value 값이 마침표 문자열(.)으로 반환된다. 이를 숫자로 파싱하면 NaN 에러가 발생하므로, parseFloat 전에 반드시 마침표 여부를 체크해야 한다.
시리즈별 업데이트 주기 차이도 중요하다. VIXCLS(VIX)는 매 영업일 갱신되지만, WALCL(연준 총자산)은 매주 수요일, M2SL(M2 통화량)은 월 1회, GDP는 분기 1회 발표된다. 대시보드 설계 시 각 시리즈의 갱신 주기에 맞춰 캐싱 전략을 달리해야 효율적이다.
frequency 파라미터 활용으로 데이터 가공을 줄일 수 있다. 일간 데이터를 월간으로 집계하고 싶을 때 클라이언트에서 직접 계산하는 대신, frequency=m과 aggregation_method=avg를 파라미터에 추가하면 서버가 월 평균값을 계산해서 반환한다.
ALFRED와의 차이도 알아두면 유용하다. FRED는 현재 최신 수정 값만 제공하는 반면, ALFRED(Archival FRED)는 과거 특정 시점에서의 빈티지 데이터를 조회할 수 있다. 경제 예측 모델의 백테스팅처럼 당시에 알 수 있었던 데이터가 필요한 경우 realtime_start와 realtime_end 파라미터를 활용하면 된다.
FRED API 응답에서 count 필드는 전체 데이터 건수를 나타낸다. 기본 limit가 100,000건이므로 대부분의 시리즈는 한 번의 호출로 전체 히스토리를 가져올 수 있다. 하지만 CPI처럼 1947년부터의 월간 데이터가 있는 시리즈도 약 950건에 불과하므로, 실질적으로 limit 초과가 발생하는 경우는 극히 드물다.
FRED API는 미국 경제 데이터의 원천 중 원천이다. 84만 개 이상의 시계열을 완전 무료로 프로그래밍 방식 접근이 가능하다는 것은 개인 투자자에게 기관급 데이터 접근성을 제공한다는 의미다.
핵심을 정리하면 이렇다. 가격은 0원이고, 분당 120회 호출 제한만 지키면 되고, JSON 응답을 간단히 파싱할 수 있으며, Python은 fredapi 패키지 3줄, JavaScript는 fetch 함수 한 번이면 데이터를 받을 수 있다. 매크로 환경 모니터링 대시보드, 투자 리서치 자동화, 경제 데이터 시각화 프로젝트 등 어떤 방향이든 FRED API가 데이터 레이어의 기반이 될 수 있다.
지금 바로 FRED 사이트에서 API 키를 발급받고, 브라우저 주소창에 첫 번째 API 호출 URL을 입력해보자. JSON 응답이 화면에 뜨는 순간, 월스트리트 트레이더들이 매일 보는 그 데이터가 자신의 프로젝트에서도 흘러가기 시작한다.