中央銀行の金利変更を追跡する

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の例は、11 December 2025適用の3.50から3.75パーセントのレンジです。関数はこのレンジを(Decimal("3.50"), Decimal("3.75"))で表します。直前に返された値と異なる場合だけ、その観測値を結果に含めます。保存済みの例には前の値がないため、変更の大きさや方向は判断できません。

銀行別の日付の意味

スウェーデン、ノルウェー、ブラジルでは、連続する行で同じ金利が繰り返される場合があります。値が異なる場合だけ変更として数えてください。米国、オーストラリア、チェコは変更日ごとの行を使用します。カナダとマレーシアでは、観測日が決定日より後になる場合があるため、観測された変化から決定日は特定できません。

どのくらいの頻度で確認すればよいですか。

金利が変わるのは決定時だけなので、1日1回の確認で十分です。現在の金利の確認には国ごとに1呼び出し、さらにリクエストする履歴ページごとに1呼び出しが必要です。この例は両国の現在の金利と履歴を読み取りますが、それぞれ別のリクエストです。

以前の結果を保存している場合は、新しい観測値を最後に保存した値と比較してください。履歴期間を狭める際も、その比較基準を保持してください。保持しないと、最初に返された観測値には比較対象となる前の値がなくなります。

日付がない場合、金利は変わらなかったという意味ですか。

日付がない場合、その日付のソース観測値が返されていないことを意味します。Narwhalは欠測日のデータを生成しません。date=YYYY-MM-DDを指定したリクエストは、指定日以前で最新のソース観測値を返します。dateを省略すると、UTCの今日を使用します。

適用日が将来の金利が、現在の金利に前倒しで置き換わることはありません。変更を記録する際は、値とともに返された日付を保持してください。レスポンス仕様は政策金利のドキュメント、リクエスト失敗時はAPIエラーを参照してください。