تتبّع تغيرات أسعار فائدة البنوك المركزية

نفّذ ذلك باستخدام واجهة API

1. اضبط مفتاح API الخاص بك اضبط متغير البيئة NARWHAL_API_KEY في البيئة التي ستشغّل Python. ثبّت مكتبة 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) قائمة من الصفوف المرتبة التي تحتوي على التاريخ والقيمة القديمة والقيمة الجديدة. القيمة الواحدة عدد عشري؛ والنطاق زوج من الأعداد العشرية بترتيب الحد الأدنى ثم الحد الأعلى. وتعني القائمة الفارغة أنه لم يُعثر على تغيرات في القيمة بين الملاحظات المُعادة.

يتضمن مثال USA المحفوظ نطاقًا من 3.50 إلى 3.75 بالمئة، ساريًا منذ 11 ديسمبر 2025. تمثل الدالة ذلك النطاق بالشكل (Decimal("3.50"), Decimal("3.75")). ولا تدرج الملاحظة في نتائجها إلا إذا اختلفت القيمة المُعادة السابقة. لا يوفر المثال المحفوظ قيمة سابقة، لذلك لا يمكنه تحديد حجم التغير أو اتجاهه.

معنى التاريخ بحسب البنك

قد تكرر السويد والنرويج والبرازيل السعر نفسه في صفوف متتالية. لا تحتسب تغيرًا إلا عندما تختلف القيمة. تستخدم الولايات المتحدة وأستراليا والتشيك صفوف تواريخ التغير. وبالنسبة إلى كندا وماليزيا، قد يكون تاريخ الملاحظة لاحقًا للقرار، لذلك لا يحدد التغير المرصود تاريخ القرار.

كم مرة ينبغي أن أجري الفحص؟

لا يتغير السعر إلا عند صدور القرارات، لذلك يكفي فحص يومي. يتطلب كل فحص للسعر الحالي استدعاءً واحدًا لكل بلد، إضافة إلى استدعاء واحد لكل صفحة من السجل التاريخي تطلبها. يقرأ المثال الأسعار الحالية والسجل التاريخي لكلا البلدين؛ وهذه طلبات منفصلة.

إذا كنت تخزن النتائج السابقة، فقارن الملاحظات الجديدة بآخر قيمة مخزنة. احتفظ بخط الأساس هذا عند تضييق النطاق الزمني للسجل التاريخي، وإلا فلن تكون للملاحظة الأولى المُعادة قيمة سابقة للمقارنة.

هل يعني غياب تاريخ أن السعر لم يتغير؟

يعني غياب تاريخ عدم وجود ملاحظة مُعادة من المصدر لذلك التاريخ. لا تختلق Narwhal بيانات للأيام المفقودة. يعيد الطلب مع date=YYYY-MM-DD أحدث ملاحظة من المصدر في التاريخ المطلوب أو قبله؛ وبدون date، يستخدم اليوم الحالي بحسب UTC.

لا تحل الأسعار ذات تواريخ السريان المستقبلية محل السعر الحالي قبل موعدها. احتفظ بالتاريخ المُعاد مع القيمة عند تسجيل تغير. استخدم توثيق سعر الفائدة الرئيسي للاطلاع على عقد الاستجابة وأخطاء API عند فشل طلب.