استخدام Jupyter API من Narwhal مع pandas

استخدم pandas وJupyter مع Narwhal API لسحب الإجازات الرسمية ومواعيد الإصدار والبيانات الاقتصادية وأسعار السلع الفورية وأسعار الصرف واحتمالات أسواق التنبؤ. أرسل طلبات موثّقة باستخدام requests، ثم حوّل حقول الاستجابة إلى pandas DataFrame.

ما الذي ستعدّه

Jupyter هو دفتر الملاحظات المستخدم في سير عمل pandas هذا: ستحصل في النهاية على دالة مساعدة للطلبات، وجداول DataFrame للسجلات المُعادة، وسعر Brent فوري رقمي. يستخدم Narwhal حسابًا واحدًا ومفتاح API واحدًا لجميع واجهات البيانات، ويتشارك REST وMCP المفتاح نفسه. يستخدم الدفتر طلبات REST إلى https://api.narwhalapi.com مع المفتاح في الترويسة Authorization: Bearer YOUR_KEY. تتضمن واجهة البيانات الاقتصادية مؤشر CPI والتضخم والناتج المحلي الإجمالي (GDP) والعوائد؛ ويستخدم هذا الدفتر ملاحظات CPI لحساب التغير الشهري.

اضبط مفتاح API الخاص بك

  1. أنشئ مفتاحًا مجانيًا احصل على مفتاح مجاني من تسجيل Narwhal. استخدم هذا المفتاح لطلبات الدفتر في جميع مجالات البيانات.
  2. تثبيت حزم الدفتر ثبّت pandas وrequests وJupyter قبل فتح الدفتر. يستخدم الكود requests لاستدعاءات HTTP وpandas للسجلات المُعادة.
    تثبيت الحزم
    pip install pandas requests jupyter
  3. ضبط المفتاح وتشغيل Jupyter استبدل YOUR_KEY بمفتاحك وصدّر NARWHAL_API_KEY قبل تشغيل Jupyter Lab. لا تضع المفتاح أبدًا في خلية دفتر تحفظها؛ إذ يقرؤه كود Python من متغير البيئة. ويستخدم البحث os.environ في الخلية اسم المتغير هذا بالضبط عند بناء ترويسة Bearer.
    تشغيل Jupyter مع المفتاح
    export NARWHAL_API_KEY=YOUR_KEY
jupyter lab

اسحب البيانات بالكود

ضع كود Python هذا في دفترك. لا يستطيع pd.read_json(url) إرسال ترويسة التفويض، لذا تنفّذ الدالة المساعدة get الطلب بـ requests وتعيد JSON. يستخدم كل DataFrame حقل الاستجابة الخاص بمجاله. يستخدم حساب CPI المستويات المُعادة لحساب التغير الشهري، بينما تُحوَّل تواريخ التوقعات بـ pd.to_datetime. تمرر الدالة معلمات الاستعلام عبر params، وترسل HEADERS مع كل استدعاء، وتضبط timeout=10. وتستدعي raise_for_status() قبل قراءة استجابة JSON. أبقِ هذه الدالة مع استدعاءات المجالات حتى يستخدم كل طلب معالجة التفويض نفسها.

pandas، ستة مجالات
import os
import pandas as pd
import requests

API = "https://api.narwhalapi.com"
HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}


def get(path, **params):
    r = requests.get(API + path, params=params, headers=HEADERS, timeout=10)
    r.raise_for_status()
    return r.json()


holidays = pd.DataFrame(get("/v1/calendars/holidays/USA/2026")["holidays"])
releases = pd.DataFrame(
    get(
        "/v1/economics/calendar",
        countries="USA",
        start_date="2026-11-01",
        end_date="2026-11-30",
        limit=100,
    )["releases"]
)
cpi = pd.DataFrame(
    get("/v1/economics/USA/cpi/observations", start="2025-09")["observations"]
)
fx = pd.DataFrame(get("/v1/fx/rates/USD", currencies="EUR,IDR")["rates"])
fed = pd.DataFrame(get("/v1/predictions/policy-paths/federal-reserve")["meetings"])
brent = float(get("/v1/commodities/spot/BRENT/USD")["price"])

cpi["value"] = cpi["value"].astype(float)
cpi["mom_pct"] = cpi["value"].pct_change() * 100
fed["resolves_at"] = pd.to_datetime(fed["resolves_at"]).dt.date

print(holidays[["date", "name"]].head(3))
print(cpi[["period", "value", "mom_pct"]].tail(3))
print(fx)
print(fed[["resolves_at", "p_cut", "p_hold", "p_hike"]].head(2))
print("Brent", brent)

في 24 أكتوبر 2026 كانت آخر ثلاثة صفوف من CPI كما يلي: يوليو 2026 عند 333.918 بتضخم شهري قدره -0.01%، وأغسطس 2026 عند 334.980 بنسبة 0.32%، وسبتمبر 2026 عند 336.940 بنسبة 0.59%. يُحسب العمود mom_pct من مستويات CPI بالتعبير pct_change() * 100.

شغّله وفق جدول

حوّل الدفتر إلى برنامج نصي باستخدام jupyter nbconvert، ثم شغّل البرنامج النصي من cron. احتفظ بالمفتاح في NARWHAL_API_KEY للبرنامج المجدول أيضًا: فإسناد HEADERS فيه يقرأ متغير البيئة نفسه الذي يقرؤه الدفتر. ويستخدم أمر التحويل pull.ipynb اسمًا لملف الدفتر.

تحويل الدفتر
jupyter nbconvert --to script pull.ipynb

يمكنك أيضًا استدعاء الدوال نفسها من مهمة مجدولة. استخدم لتلك المهمة الدالة المساعدة للطلبات واستدعاءات المجالات من الدفتر، مع تمرير ترويسة Bearer عبر HEADERS. ولمعرفة كيفية جدولة السحب راجع جدولة سحب يومي للبيانات.

الإجازات الرسمية في pandas

اقرأ الإجازات الرسمية في الولايات المتحدة لعام 2026 من حقل الاستجابة holidays. لكل إجازة date وname، فيعرض لك هذان العمودان تاريخ الإجازة إلى جانب اسمها في الدفتر. تستخدم هذه العيّنة الدالة المساعدة get الموثّقة نفسها المستخدمة في الخلية الكاملة وتختار هذه الحقول للعرض. عرّف الدالة المساعدة قبل استخدام عيّنات المجالات.

اقرأ تواريخ الإجازات وأسماءها
data = get("/v1/calendars/holidays/USA/2026")
holidays = pd.DataFrame(data["holidays"])
print(holidays[["date", "name"]].head(3))

مواعيد الإصدار في pandas

اسحب من التقويم الاقتصادي إصدارات الولايات المتحدة من 1 نوفمبر 2026 حتى 30 نوفمبر 2026 مع limit=100. حقل الاستجابة هو releases، وتضم سجلاته at وperiod وtopic وstatus التي يمكنك عرضها معًا في DataFrame. استخدم هذا الاستدعاء لمواعيد الإصدار، واستخدم استدعاء الملاحظات في عيّنة الاقتصاد لمستويات CPI حسب الفترة.

قراءة مواعيد الإصدار الاقتصادية
data = get(
    "/v1/economics/calendar",
    countries="USA",
    start_date="2026-11-01",
    end_date="2026-11-30",
    limit=100,
)
releases = pd.DataFrame(data["releases"])
print(releases[["at", "period", "topic", "status"]])

البيانات الاقتصادية في pandas

اطلب رصدات CPI للولايات المتحدة (USA) مع start=2025-09 واقرأ observations في DataFrame. يحتوي كل سجل على period وvalue. حوّل عمود القيمة قبل حساب التغيرات الشهرية.

حساب التغير الشهري في CPI
data = get("/v1/economics/USA/cpi/observations", start="2025-09")
cpi = pd.DataFrame(data["observations"])
cpi["value"] = cpi["value"].astype(float)
cpi["mom_pct"] = cpi["value"].pct_change() * 100
print(cpi[["period", "value", "mom_pct"]].tail(3))

الأسعار الفورية للسلع في pandas

يقرأ استدعاء Brent الحقل price ويحوّله إلى float. ويستخدم BRENT رمزًا للسعر الفوري وUSD في مسار الطلب. تشمل رموز الأسعار الفورية على سبيل المثال XAU وXAG وXPT وXPD وXCU وBRENT وWTI. أبقِ مسار Brent كما هو في هذه العيّنة، واستخدم القيمة الرقمية التي يعيدها float في دفترك.

قراءة سعر Brent الفوري
data = get("/v1/commodities/spot/BRENT/USD")
brent = float(data["price"])
print("Brent", brent)

أسعار الصرف في pandas

استخدم مسار أسعار USD مع currencies=EUR,IDR لطلب أسعار الصرف في هذه العيّنة. اقرأ الحقل rates في DataFrame؛ ولكل سجل مُعاد currency وrate. يؤدي اختيار هذين العمودين إلى إبقاء العملة بجانب سعرها. يستخدم هذا الطلب المفتاح والترويسة نفسيهما المستخدمين في استدعاءي CPI والإجازات.

قراءة أسعار صرف USD
data = get("/v1/fx/rates/USD", currencies="EUR,IDR")
fx = pd.DataFrame(data["rates"])
print(fx[["currency", "rate"]])

احتمالات أسواق التنبؤ في pandas

اقرأ مسار سياسة الاحتياطي الفيدرالي من الحقل meetings. لكل اجتماع resolves_at وp_cut وp_hold وp_hike. حوّل resolves_at إلى تاريخ بتعبير pandas نفسه المستخدم في الخلية الكاملة، ثم اعرضه بجانب حقول الاحتمالات. وبذلك يظهر تاريخ حسم الاجتماع وحقول الخفض والإبقاء والرفع معًا في مخرجات الدفتر.

قراءة اجتماعات مسار السياسة
data = get("/v1/predictions/policy-paths/federal-reserve")
fed = pd.DataFrame(data["meetings"])
fed["resolves_at"] = pd.to_datetime(fed["resolves_at"]).dt.date
print(fed[["resolves_at", "p_cut", "p_hold", "p_hike"]].head(2))

لماذا تظهر أرقامي نصوصًا؟

تعيد API الأعداد العشرية نصوصًا للحفاظ على الدقة. استخدم astype(float) على عمود في DataFrame عندما تحتاج إلى حسابات رقمية، كما في cpi["value"].astype(float). وفي سعر Brent المفرد تستخدم العيّنة float على الحقل price المُعاد. طبّق التحويل على القيم التي تحتاجها للحساب فقط. وتبقى أسماء حقول الاستجابة كما هي بعد أن تصبح القيم رقمية.

كيف أحصل على التغير السنوي؟

استدعِ /v1/economics/USA/inflation للحصول على المعدل العام. يُرجع year_over_year وmonth_over_month. يحتاج احتساب التغير السنوي من مستويات CPI إلى المستوى قبل 12 شهرًا من الشهر المقارَن، لذا اطلب 13 شهرًا على الأقل من المستويات.

نُشر في .

الخطوات التالية