跟踪央行利率变动

使用 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. 读取历史数据并分页 使用 start=2024-01-01 请求 /v1/economics/{country}/central-bank/policy-rate/history。按返回顺序读取观测记录，然后将 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) 返回元组列表，每个元组包含日期、旧值和新值。单点值为十进制数；区间为一对十进制数，按下限、上限的顺序排列。空列表表示在返回的观测记录之间未发现数值变化。

保存的 USA 示例中，区间为 3.50 至 3.75 百分比，生效日期为 11 December 2025。函数将该区间表示为 (Decimal("3.50"), Decimal("3.75"))。只有当前一条返回的数值不同时，才会将该观测记录纳入结果。保存的示例未提供前一个数值，因此无法确定变动幅度或方向。

各央行日期的含义

瑞典、挪威和巴西的连续记录可能具有相同利率。仅在数值不同时计为一次变动。美国、澳大利亚和捷克采用变动日期记录。对于加拿大和马来西亚，观测日期可能晚于决策日期，因此观测到的变动不能确定决策日期。

应该多久检查一次？

利率仅在作出决策时变化，因此每天检查一次即可。每次当前利率检查按每个国家计一次调用，另外每请求一页历史数据计一次调用。示例读取两个国家的当前利率和历史数据；这些都是独立请求。

如果存储了以前的结果，请将新观测记录与最后存储的数值比较。缩小历史时间范围时请保留该基准，否则第一条返回的观测记录将没有前一个数值可供比较。

缺失日期是否意味着利率没有变化？

缺失日期表示没有返回该日期的源观测记录。Narwhal 不会为缺失日期编造数据。带有 date=YYYY-MM-DD 的请求返回指定日期当天或之前最新的源观测记录；省略 date 时，使用 UTC 当日。

未来生效的利率不会提前替换当前利率。记录变动时，请保留随数值返回的日期。响应契约详见政策利率文档，请求失败时请参阅 API 错误。