(OpenAPI)FRED API 사용: 미국금리 시계열 분석 1(python)

API 활용 방법

FRED API를 python 환경에서 쉽게 사용하기 위해서 fredapi라는 라이브러리가 공식적으로 제공되고 있다.(https://pypi.org/project/fredapi/) 아래 명령어로 간단하게 설치가 가능하며, 조금 더 쉽게 FRED API를 사용할 수 있다. 

pip install fredapi

하지만 FRED API 구조가 복잡한 부분이 없어서 fredapi 라는 라이브러리의 도움 없이도 충분히 함수를 만들어서 FRED API를 활용할 수 있다.

API 활용 기본구조

FRED API 는 주로 과거 시계열을 보는데 유용하기 때문에 공식문서에서 series 부분을 주로 참조하게 된다. 여기에서 데이터 제공 형식, API 요청 시 parameters 등을 함께 확인할 수 있다.

그림1: fred/series/observations

series에서 제공하는 Examples를 통해서 API 요청을 위한 기본적인 URL을 파악할 수 있으며, 제공되는 데이터 형식은 xml, json 이라는 점, series_id라는 변수를 통해 데이터를 구분한다는 점, 시작일과 종료일의 설정할 수 있다는 점 등을 공식문서에서 확인할 수 있다.  

그림2: FRED API 활용을 위한 기본 URL 및 parameter 확인

지금까지의 정보를 바탕으로 request 라이브러리를 활용해서 아래와 같은 구조로 FRED series/observations에서 데이터를 받아오는 코드를 짤 수 있다. 

def get_result(api_key: str, stdate: str, eddate: str, series_id: str):
    # FRED(Federal Reserve Economic Data) API의 시계열 데이터 요청 URL
    url = "https://api.stlouisfed.org/fred/series/observations"
  
    # API 요청 파라미터 설정
    params = {
        "series_id": series_id,          # 예: "GS10" (10년 만기 국채 금리 등)
        "api_key": api_key,              # 사용자 API 키
        "file_type": "json",             # 응답 형식: JSON
        "frequency": "m",                # 월간(monthly) 데이터
        "observation_start": stdate,     # 시작일 (예: "2023-01-01")
        "observation_end": eddate        # 종료일 (예: "2024-12-31")
    }
    
    # GET 요청 보내기
    res = requests.get(url, params=params)
    
    # 오류 발생 시 예외 처리 (응답 코드가 4xx, 5xx일 경우)
    res.raise_for_status()
    
    # 응답 결과(JSON)를 출력 (디버깅용)
    print(res.json())

get_result 함수를 실행해서 JSON 결과를 받아보면 아래 그림 3과 같은 결과가 나오는데, observations에 딕셔너리 형태로 결과가 붙어있는 것을 확인할 수 있다. 

그림3: API에 요청에 대한 JSON 응답 예시

observations 내용만 뽑아낸 뒤 date와 value컬럼을 가진 데이터프레임을 return 하는 get_result 함수는 아래와 같이 완성할 수 있다. 

def get_result(api_key: str, stdate: str, eddate: str, series_id: str):
   ... (생략)...
   
    # 에러 발생 시 예외 발생 (응답 코드가 4xx, 5xx일 경우)
    res.raise_for_status()
  
    # JSON 응답에서 'observations' 키에 해당하는 데이터만 가져와 DataFrame으로 생성
    df = pd.DataFrame(res.json()["observations"], columns=["date", "value"])
    
    # 컬럼명을 ['date', 시리즈명]으로 변경 (value → 시리즈 ID)
    df.columns = ["date", series_id]
    
    # 날짜 문자열을 datetime 타입으로 변환
    df["date"] = pd.to_datetime(df["date"])
    
    # 금리 값(value)을 float 타입으로 변환 (기본은 문자열로 들어옴)
    df[series_id] = df[series_id].astype(float)
    
    # 최종 DataFrame 반환
    return df

조회ID 확인하기

get_result 함수 내에서 request 라이브러리를 통한 요청을 보낼 때 가장 중요한 것이 series_id이다. 데이터를 나타내는 코드인데, 이 코드는 FRED 본 사이트(https://fred.stlouisfed.org/)에서 찾고자 하는 데이터를 검색해 보면 알 수 있다. 예시로 미국채 5년물 월별 데이터의 코드를 확인해보자. 먼저 아래 그림 4와 같이 "5 year us treasury monthly"라고 검색해서 미국채 5년물 월별 데이터를 검색한다.

그림4: 미국채 5년물 월별 데이터

해당 항목을 클릭하면 URL 맨 끝에 나오는 코드(여기에서는 GS5)가 바로 series_id이다.

그림5: series_id 확인

미국금리 데이터 입수

최종적으로 미리 만들어 둔 get_result 함수에 api_key, 시작일, 종료일, "GS5"를 넣으면 미국 5년물 월별 금리 추이를 받을 수 있다. 아래는 완성된 코드와 출력되는 결과를 나타낸 그림이다.

import requests
import pandas as pd

api_key = "나의 API 키"
stdate = "2020-05-11"
eddate = "2025-05-11"

def get_result(api_key: str, stdate: str, eddate: str, series_id: str):
    url = "https://api.stlouisfed.org/fred/series/observations"
    params={"series_id": series_id,         
            "api_key": api_key,
            "file_type": "json",
            "frequency": "m",
            "observation_start": stdate,
            "observation_end": eddate}
    res = requests.get(url, params=params)
    res.raise_for_status()
    df = pd.DataFrame(res.json()["observations"], columns=["date", "value"])
    df.columns = ["date", series_id]
    df["date"] = pd.to_datetime(df["date"])
    df[series_id] = df[series_id].astype(float)
    return df

df_gs05 = get_result(api_key, stdate, eddate, "GS5")
print(df_gs05)