追蹤中央銀行利率變動

使用 API

1. 設定你的 API 金鑰 在執行 Python 的環境中設定 NARWHAL_API_KEY 環境變數。為該直譯器安裝 requests 函式庫。公開存取開放後，所有方案皆可即時請求政策利率，包括 Free。每次請求消耗一個用量單位，歷史資料的每一頁也各計一次。
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. 讀取歷史資料並處理分頁 請求 /v1/economics/{country}/central-bank/policy-rate/history，並傳入 start=2024-01-01。依回傳順序讀取觀測資料，再將 next_cursor 作為 cursor 傳入，直到其值為 null。跨頁時請保留前一筆數值。程式使用 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 金鑰，並設定 PATH，使其能找到已安裝 requests 的直譯器。程式在預覽兩個目前利率回應後，只會印出有變動的觀測資料。
   讀取目前利率回應並偵測歷史變動

   複製

   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) 會回傳 tuple 清單，每個 tuple 包含日期、舊值與新值。單一利率值為十進位數值；區間則是一對十進位數值，依下限、上限順序排列。空清單表示回傳的觀測資料之間未發現數值變動。

已儲存的 USA 範例區間為百分之 3.50 至 3.75，自 11 December 2025 生效。函式將該區間表示為 (Decimal("3.50"), Decimal("3.75"))。只有在前一筆回傳數值不同時，才會將此觀測資料納入結果。已儲存的範例未提供前一筆數值，因此無法判定變動幅度或方向。

各央行日期的意義

瑞典、挪威及巴西的連續資料列可能重複相同利率。只有數值不同時才計為一次變動。美國、澳洲及捷克採用變動日期資料列。加拿大與馬來西亞的觀測日期可能晚於決策日期，因此觀測到變動並不能確定決策日期。

應該多久檢查一次？

利率只會在決策時變動，因此每日檢查一次即可。每次檢查目前利率，每個國家計一次呼叫，另外每請求一頁歷史資料也計一次呼叫。範例會讀取兩個國家的目前利率與歷史資料；這些是各自獨立的請求。

如果有儲存先前結果，請將新的觀測資料與最後儲存的數值比較。縮小歷史期間時，請保留此基準，否則第一筆回傳的觀測資料將沒有前一筆數值可供比較。

缺漏日期代表利率沒有變動嗎？

缺漏日期表示該日期沒有回傳的來源觀測資料。Narwhal 不會虛構缺漏日期的資料。帶有 date=YYYY-MM-DD 的請求會回傳指定日期或之前最新的來源觀測資料；未提供 date 時，則使用 UTC 今日。

未來才生效的利率不會提前取代目前利率。記錄變動時，請保留與數值一併回傳的日期。回應契約請參閱政策利率文件，請求失敗時請參閱 API 錯誤。