중앙은행 금리 변동 추적

API 사용 방법

1. API 키 설정 Python을 실행할 환경에 NARWHAL_API_KEY 환경 변수를 설정하세요. 해당 인터프리터에 requests 라이브러리를 설치하세요. 공개 이용이 시작되면 Free를 포함한 모든 요금제에서 정책금리를 실시간으로 요청할 수 있습니다. 이력의 각 페이지를 포함하여 요청마다 사용량 1단위가 차감됩니다.
2. 현재 금리 조회 /v1/economics/USA/central-bank/policy-rate와 /v1/economics/CAN/central-bank/policy-rate를 요청하세요. 국가 코드는 대문자 ISO3를 사용합니다. USA 응답에는 rate_type: "range", lower_bound, upper_bound가 있습니다. 캐나다 응답에는 rate_type: "point", rate, qualifier가 있습니다. 값은 연율 백분율을 나타내는 소수 문자열입니다. 전체 스크립트는 두 응답을 모두 출력하므로 구조를 확인할 수 있습니다.
3. 이력 조회와 페이지 처리 start=2024-01-01로 /v1/economics/{country}/central-bank/policy-rate/history를 요청하세요. 반환된 순서대로 관측값을 읽고, next_cursor가 null이 될 때까지 이를 cursor로 전달하세요. 페이지가 바뀌어도 이전 값을 유지하세요. 스크립트는 params=로 쿼리 값을 인코딩합니다. 커서는 발표 데이터의 버전을 24시간 동안 고정하며, 만료된 커서는 409를 반환합니다.
4. 연속된 값 비교 각 단일 금리 관측값의 rate를 이전 단일 값과 비교하세요. 범위는 lower_bound와 upper_bound 쌍을 비교하세요. 비교하기 전에 문자열을 십진수로 변환하세요. 첫 관측값은 기준값이 되므로, 함수는 이 관측값이 요청한 이력 조회 기간 이전의 값에서 변경되었는지 판단할 수 없습니다.
5. 반환된 날짜 선택 effective_on이 있으면 출력하고, 없으면 observed_on을 출력하세요. 각 응답에는 이 필드 중 정확히 하나만 있습니다. 선택적 필드 announced_on은 발표일을 나타냅니다. 이력에는 단일 금리와 범위가 모두 포함될 수 있으므로 관측값을 저장할 때 반환된 금리 지표와 금리 구조를 유지하세요. 비교 함수는 값에서 이 구분을 보존합니다.
6. 스크립트 매일 실행 전체 예제를 홈 디렉터리에 track_rates.py로 저장하세요. 키를 설정한 상태에서 한 번 실행한 다음, 0 0 * * * /usr/bin/env python3 "$HOME/track_rates.py"로 매일 실행하도록 예약하세요. 예약 실행 환경에 API 키를 설정하고, requests가 설치된 인터프리터를 찾을 수 있도록 PATH를 구성하세요. 스크립트는 현재 응답 미리보기 2개를 출력한 후 변경된 관측값만 출력합니다.
   현재 응답 조회와 과거 변경 감지

   복사

   import json
   import os
   from decimal import Decimal
   
   import requests
   
   BASE_URL = "https://api.narwhalapi.com"
   START = "2024-01-01"
   HEADERS = {
       "Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"
   }
   
   
   def get_json(path, params=None):
       response = requests.get(
           BASE_URL + path,
           headers=HEADERS,
           params=params,
           timeout=10,
       )
       response.raise_for_status()
       return response.json()
   
   
   def rate_value(observation):
       if observation["rate_type"] == "point":
           return Decimal(observation["rate"])
       if observation["rate_type"] == "range":
           return (
               Decimal(observation["lower_bound"]),
               Decimal(observation["upper_bound"]),
           )
       raise ValueError("Unexpected rate_type")
   
   
   def changes(country):
       path = f"/v1/economics/{country}/central-bank/policy-rate/history"
       params = {"start": START}
       previous = None
       result = []
   
       while True:
           page = get_json(path, params=params)
           for observation in page["observations"]:
               current = rate_value(observation)
               if previous is not None and current != previous:
                   date = (
                       observation["effective_on"]
                       if "effective_on" in observation
                       else observation["observed_on"]
                   )
                   result.append((date, previous, current))
               previous = current
   
           cursor = page["next_cursor"]
           if cursor is None:
               return result
           params = {"start": START, "cursor": cursor}
   
   
   if __name__ == "__main__":
       for country in ("USA", "CAN"):
           current = get_json(
               f"/v1/economics/{country}/central-bank/policy-rate"
           )
           print(json.dumps(current, indent=2))
           for date, old, new in changes(country):
               print(country, date, old, new)
   

changes(country) 함수는 날짜, 이전 값, 새 값을 담은 튜플 목록을 반환합니다. 단일 값은 십진수이며, 범위는 하한, 상한 순서의 십진수 쌍입니다. 빈 목록은 반환된 관측값 사이에서 값의 변경을 찾지 못했다는 뜻입니다.

저장된 USA 예제의 범위는 3.50~3.75%이며, 적용일은 2025년 12월 11일입니다. 함수는 이 범위를 (Decimal("3.50"), Decimal("3.75"))로 나타냅니다. 직전에 반환된 값이 다를 때만 해당 관측값을 결과에 포함합니다. 저장된 예제에는 이전 값이 없으므로 변경의 크기나 방향을 판단할 수 없습니다.

은행별 날짜의 의미

스웨덴, 노르웨이, 브라질은 연속된 행에서 같은 금리가 반복될 수 있습니다. 값이 다를 때만 변경으로 집계하세요. 미국, 호주, 체코는 변경일별 행을 사용합니다. 캐나다와 말레이시아는 관측일이 결정일보다 늦을 수 있으므로, 관측된 변경만으로 결정일을 확인할 수 없습니다.

얼마나 자주 확인해야 하나요?

금리는 결정 시에만 변경되므로 하루에 한 번 확인하면 충분합니다. 현재 금리 확인은 국가당 호출 1회이며, 요청하는 이력 페이지당 호출 1회가 추가됩니다. 예제는 두 국가의 현재 금리와 이력을 조회하며, 각각 별도 요청입니다.

이전 결과를 저장한다면 새 관측값을 마지막으로 저장한 값과 비교하세요. 이력 조회 기간을 좁힐 때도 이 기준값을 유지하세요. 그렇지 않으면 첫 번째 반환 관측값과 비교할 이전 값이 없어집니다.

날짜가 없으면 금리가 바뀌지 않았다는 뜻인가요?

날짜가 없다는 것은 해당 날짜에 반환된 원본 관측값이 없다는 뜻입니다. Narwhal은 누락된 날짜를 임의로 만들지 않습니다. date=YYYY-MM-DD를 지정한 요청은 요청 날짜 또는 그 이전의 최신 원본 관측값을 반환합니다. date가 없으면 UTC 기준 오늘을 사용합니다.

적용일이 미래인 금리는 현재 금리를 미리 대체하지 않습니다. 변경을 기록할 때는 값과 함께 반환된 날짜를 보존하세요. 응답 명세는 정책금리 문서를, 요청 실패 시에는 API 오류를 확인하세요.