pandas 금융 데이터와 Jupyter로 Narwhal API 사용하기

설정할 내용

Jupyter는 이 pandas 워크플로를 위한 노트북입니다. 결과적으로 요청 헬퍼, 반환된 레코드의 DataFrame, 숫자로 된 Brent 현물 가격을 얻게 됩니다. Narwhal은 하나의 계정과 하나의 API 키로 모든 데이터 API를 이용하며, REST와 MCP도 같은 키를 공유합니다. 노트북은 https://api.narwhalapi.com으로 REST 요청을 보내고, 키는 Authorization: Bearer YOUR_KEY 헤더에 넣습니다. 경제 데이터 API에는 CPI, 인플레이션, GDP, 수익률이 포함되며, 이 노트북은 CPI 관측값으로 전월 대비 변화율을 계산합니다.

API 키 설정

1. 무료 키 만들기 Narwhal 가입에서 무료 키를 받으세요. 이 키를 노트북의 모든 데이터 분야 요청에 사용합니다.
2. 노트북 패키지 설치하기 노트북을 열기 전에 pandas, requests, Jupyter를 설치하세요. 코드는 HTTP 호출에 requests를, 반환된 레코드 처리에 pandas를 사용합니다.
   패키지 설치

   pip install pandas requests jupyter

3. 키를 설정하고 Jupyter 시작하기 YOUR_KEY를 본인의 키로 바꾸고, Jupyter Lab을 시작하기 전에 NARWHAL_API_KEY를 export하세요. 저장하는 노트북 셀에는 키를 절대 넣지 마세요. Python 코드는 환경 변수에서 키를 읽습니다. 셀의 os.environ 조회는 Bearer 헤더를 만들 때 이 변수 이름을 그대로 사용합니다.
   키와 함께 Jupyter 시작하기

   export NARWHAL_API_KEY=YOUR_KEY
   jupyter lab

코드로 데이터 가져오기

이 Python 코드를 노트북에 넣으세요. pd.read_json(url)은 인증 헤더를 보낼 수 없으므로, get 헬퍼가 requests로 요청하고 JSON을 반환합니다. 각 DataFrame은 해당 분야의 응답 필드를 사용합니다. CPI 계산은 반환된 수준값으로 전월 대비를 구하고, 예측 날짜는 pd.to_datetime으로 변환합니다. 헬퍼는 쿼리 매개변수를 params로 전달하고, 호출마다 HEADERS를 보내며, timeout=10을 설정합니다. JSON 응답을 읽기 전에 raise_for_status()를 호출합니다. 각 요청이 같은 인증 처리를 쓰도록 이 헬퍼를 분야별 호출과 함께 두세요.

import os
import pandas as pd
import requests

API = "https://api.narwhalapi.com"
HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}


def get(path, **params):
    r = requests.get(API + path, params=params, headers=HEADERS, timeout=10)
    r.raise_for_status()
    return r.json()


holidays = pd.DataFrame(get("/v1/calendars/holidays/USA/2026")["holidays"])
releases = pd.DataFrame(
    get(
        "/v1/economics/calendar",
        countries="USA",
        start_date="2026-11-01",
        end_date="2026-11-30",
        limit=100,
    )["releases"]
)
cpi = pd.DataFrame(
    get("/v1/economics/USA/cpi/observations", start="2025-09")["observations"]
)
fx = pd.DataFrame(get("/v1/fx/rates/USD", currencies="EUR,IDR")["rates"])
fed = pd.DataFrame(get("/v1/predictions/policy-paths/federal-reserve")["meetings"])
brent = float(get("/v1/commodities/spot/BRENT/USD")["price"])

cpi["value"] = cpi["value"].astype(float)
cpi["mom_pct"] = cpi["value"].pct_change() * 100
fed["resolves_at"] = pd.to_datetime(fed["resolves_at"]).dt.date

print(holidays[["date", "name"]].head(3))
print(cpi[["period", "value", "mom_pct"]].tail(3))
print(fx)
print(fed[["resolves_at", "p_cut", "p_hold", "p_hike"]].head(2))
print("Brent", brent)

2026년 10월 24일 기준으로 최근 CPI 세 행은 2026년 7월 333.918(전월 대비 -0.01%), 2026년 8월 334.980(0.32%), 2026년 9월 336.940(0.59%)이었습니다. mom_pct 열은 CPI 수준값에서 pct_change() * 100으로 계산합니다.

일정에 맞춰 실행하기

jupyter nbconvert로 노트북을 스크립트로 변환한 뒤, 그 스크립트를 cron에서 실행하세요. 예약 실행하는 스크립트에서도 키는 NARWHAL_API_KEY에 보관합니다. HEADERS 할당이 노트북과 같은 환경 변수를 읽습니다. 변환 명령에서는 노트북 파일 이름으로 pull.ipynb를 사용합니다.

jupyter nbconvert --to script pull.ipynb

같은 함수를 예약된 작업에서 호출할 수도 있습니다. 그 작업에는 노트북의 요청 헬퍼와 분야별 호출을 사용하고, Bearer 헤더는 HEADERS로 전달합니다. 데이터 가져오기 예약에 대해서는 매일 데이터 가져오기 예약하기를 참고하세요.

pandas에서 공휴일 사용하기

2026년 미국 공휴일을 holidays 응답 필드에서 읽으세요. 각 공휴일에는 date와 name이 있으므로, 노트북에서 이 열들로 공휴일 날짜와 이름을 나란히 볼 수 있습니다. 이 샘플은 전체 셀과 같은 인증된 get 헬퍼를 사용하고, 표시를 위해 해당 필드를 선택합니다. 분야별 샘플을 사용하기 전에 헬퍼를 먼저 정의해 두세요.

data = get("/v1/calendars/holidays/USA/2026")
holidays = pd.DataFrame(data["holidays"])
print(holidays[["date", "name"]].head(3))

pandas에서 발표일 사용하기

경제 캘린더에서 2026년 11월 1일부터 2026년 11월 30일까지의 미국 발표 데이터를 limit=100으로 가져옵니다. 응답 필드는 releases이며, 각 레코드에는 at, period, topic, status가 있어 DataFrame에 함께 표시할 수 있습니다. 발표일에는 이 호출을 쓰고, 기간별 CPI 수준값에는 경제 데이터 샘플의 관측값 호출을 사용하세요.

data = get(
    "/v1/economics/calendar",
    countries="USA",
    start_date="2026-11-01",
    end_date="2026-11-30",
    limit=100,
)
releases = pd.DataFrame(data["releases"])
print(releases[["at", "period", "topic", "status"]])

pandas에서 경제 데이터 사용하기

start=2025-09로 USA CPI 관측값을 요청하고 observations를 DataFrame으로 읽어 들이세요. 각 레코드에는 period와 value가 있습니다. 전월 대비 변화를 계산하기 전에 value 열을 변환하세요.

data = get("/v1/economics/USA/cpi/observations", start="2025-09")
cpi = pd.DataFrame(data["observations"])
cpi["value"] = cpi["value"].astype(float)
cpi["mom_pct"] = cpi["value"].pct_change() * 100
print(cpi[["period", "value", "mom_pct"]].tail(3))

pandas에서 원자재 현물 가격 사용하기

Brent 호출은 price 필드를 읽어 float로 변환합니다. 현물 코드로 BRENT를, 요청 경로에 USD를 사용합니다. 현물 코드에는 예를 들어 XAU, XAG, XPT, XPD, XCU, BRENT, WTI가 있습니다. 이 샘플에서는 Brent 경로를 그대로 두고, float가 반환하는 숫자 값을 노트북에서 사용하세요.

data = get("/v1/commodities/spot/BRENT/USD")
brent = float(data["price"])
print("Brent", brent)

pandas에서 환율 사용하기

이 샘플의 환율은 USD 환율 경로에 currencies=EUR,IDR를 붙여 요청합니다. rates 필드를 DataFrame으로 읽으면 반환된 각 레코드에 currency와 rate가 있습니다. 이 열들을 선택하면 통화를 환율 옆에 둘 수 있습니다. 이 요청은 CPI 및 공휴일 호출과 같은 키와 헤더를 사용합니다.

data = get("/v1/fx/rates/USD", currencies="EUR,IDR")
fx = pd.DataFrame(data["rates"])
print(fx[["currency", "rate"]])

pandas에서 예측 시장 확률 사용하기

연방준비제도 정책 경로를 meetings 필드에서 읽으세요. 각 회의에는 resolves_at, p_cut, p_hold, p_hike가 있습니다. 전체 셀과 같은 pandas 표현식으로 resolves_at을 날짜로 변환한 뒤, 확률 필드와 나란히 표시하세요. 이렇게 하면 회의의 결정일과 인하, 동결, 인상 필드가 노트북 출력에 함께 모입니다.

data = get("/v1/predictions/policy-paths/federal-reserve")
fed = pd.DataFrame(data["meetings"])
fed["resolves_at"] = pd.to_datetime(fed["resolves_at"]).dt.date
print(fed[["resolves_at", "p_cut", "p_hold", "p_hike"]].head(2))

숫자가 왜 텍스트로 나오나요?

API는 정밀도를 유지하려고 소수를 문자열로 반환합니다. 숫자 계산이 필요하면 DataFrame 열에 astype(float)를 사용하세요. 예를 들면 cpi["value"].astype(float)처럼 씁니다. 단일 Brent 가격에서는 샘플이 반환된 price 필드에 float를 사용합니다. 변환은 산술에 필요한 값에만 적용하세요. 값이 숫자가 되어도 응답 필드 이름은 그대로입니다.

전년 대비는 어떻게 구하나요?

종합 상승률은 /v1/economics/USA/inflation을 호출해 확인하세요. year_over_year와 month_over_month가 반환됩니다. CPI 수준값으로 전년 대비를 계산하려면 비교할 달의 12개월 전 수준값이 필요하므로 최소 13개월 분량을 요청하세요.