استخدام Narwhal عبر API بايثون بيانات مالية

يمكنك استخدام بايثون وNarwhal لجلب الإجازات الرسمية وتواريخ الإصدار والبيانات الاقتصادية وأسعار السلع الفورية وأسعار الصرف واحتمالات أسواق التنبؤ بمفتاح API واحد. استخدم requests لقراءة استجابات JSON، ثم جدول السكربت عبر cron للجلب اليومي.

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

تمنحك بايثون 3 مع requests سكربتًا يستدعي Narwhal REST API ويقرأ حقول الاستجابة لكل مجال بيانات. ستحصل على دالة مساعدة مشتركة للطلبات، ومثال لكل مجال، وإدخال cron يوميّ. يستخدم Narwhal حسابًا واحدًا ومفتاح API واحدًا عبر واجهات البيانات التابعة له؛ ويشترك REST وMCP في المفتاح نفسه. تستخدم الأمثلة https://api.narwhalapi.com عنوانَ قاعدة وترسل Authorization: Bearer YOUR_KEY. تختار المسارات مجال البيانات، وتقرأ كل استدعاء الحقل المطابق من استجابة JSON.

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

  1. أنشئ مفتاحًا مجانيًا أنشئ مفتاحك المجاني من narwhalapi.com/signup. يوضع المفتاح نفسه في رأس Authorization لكل طلب، لذا يمكنك استخدامه في السكربت كله.
  2. احفظ المفتاح في بيئة الطرفية اضبط NARWHAL_API_KEY في الطرفية التي ستستخدم فيها curl وبايثون، مستبدلًا العنصر النائب بمفتاحك. تقرأ الدالة المساعدة في بايثون متغير البيئة هذا عند بناء رأس Bearer.
    مفتاح API
    export NARWHAL_API_KEY=...
  3. ثبّت requests لبايثون 3 ثبّت requests لسكربت بايثون. توجد أيضًا حزمة narwhalapi SDK على PyPI، ويمكن تثبيتها بالأمر pip install narwhalapi.
    تثبيت requests
    pip install requests

اجلب البيانات قبل كتابة بايثون

  1. اطلب JSON الإجازات الرسمية استخدم curl مع متغير البيئة الذي ضبطته في الطرفية. يرسل هذا الطلب رأس Bearer إلى نقطة نهاية الإجازات الرسمية ويطبع JSON قبل أن تكتب شيفرة بايثون.
    طلب الإجازات الرسمية
    curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/calendars/holidays/USA/2026"
  2. اقرأ صفوف الإجازات الرسمية ابحث عن الصفوف المعادة في holidays. لكل صف date وname؛ ويستخدم مثال بايثون هذين الحقلين لطباعة أول إجازة بعد عدّ الصفوف.

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

استخدم الدالة المساعدة المشتركة get في الطلبات الستة كلها. تجمع بين عنوان القاعدة للـ API والمسار، وترسل الرأس، وتمرر معاملات الاستعلام، وتقرأ JSON بعد raise_for_status(). ثم تختار الاستدعاءات حقل الاستجابة لكل مجال، فتستطيع عبارات print التعامل مع صفوف الإجازات الرسمية وتواريخ الإصدار والملاحظات وسعر فوري وأسعار الصرف واحتمالات الاجتماعات.

تبقى معاملات الاستعلام مع كل استدعاء على حدة: يتضمن طلب تواريخ الإصدار الدولة وحدود التاريخ والحد الأقصى، بينما يتضمن طلب الصرف العملات. ترسلها الدالة المساعدة عبر params ثم تعيد الاستجابة بعد تحليلها. ضع الدالة المساعدة فوق أمثلة المجالات ليتمكن كل مثال من استخدام get وAPI وHEADERS. يعيد كل مثال أدناه استخدام هذه الدالة بمساره وحقل استجابته.

بايثون، المجالات الستة كلها
import os
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 = get("/v1/calendars/holidays/USA/2026")["holidays"]
releases = get(
    "/v1/economics/calendar",
    countries="USA",
    start_date="2026-11-01",
    end_date="2026-11-30",
    limit=100,
)["releases"]
cpi = get("/v1/economics/USA/cpi/observations", start="2025-09")["observations"]
brent = get("/v1/commodities/spot/BRENT/USD")["price"]
fx = get("/v1/fx/rates/USD", currencies="EUR,IDR")["rates"]
fed = get("/v1/predictions/policy-paths/federal-reserve")["meetings"]

print(len(holidays), holidays[0]["date"], holidays[0]["name"])
print(len(releases), releases[0]["period"], releases[0].get("at"))
print(cpi[-1]["period"], cpi[-1]["value"])
print("Brent", brent)
print({r["currency"]: r["rate"] for r in fx})
print(fed[0]["resolves_at"][:10], fed[0]["p_hold"])

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

يمكن لإدخال cron تشغيل السكربت مرة في اليوم. استخدم الإدخال المرفق مع سكربتك في /path/pull.py؛ فهو يستدعي /usr/bin/python3 ويضيف الناتج المطبوع إلى pull.log. ينفّذ السكربت ستة استدعاءات في اليوم، وهو عدد قليل من الطلبات.

إدخال cron اليومي
0 7 * * * /usr/bin/python3 /path/pull.py >> pull.log

اضبط NARWHAL_API_KEY في البيئة التي تعمل فيها المهمة. على جهاز مشترك، ضع المفتاح في ملف تحمّله المهمة، وأبقه خارج crontab. يقرأ السكربت المجدول المتغير نفسه المستخدم في مثال الطرفية، وتستخدم طلباته رأس Bearer نفسه.

الإجازات الرسمية في بايثون

اقرأ holidays للحصول على تاريخ كل إجازة واسمها. تحتوي استجابة 24 أكتوبر 2026 على 11 إجازة رسمية في الولايات المتحدة لعام 2026، وأولها رأس السنة في 1 يناير. يستخدم هذا المثال الدالة المساعدة المشتركة ويطبع هذين الحقلين من الصف الأول؛ ويطبع السكربت الكامل أيضًا عدد صفوف الإجازات.

تواريخ الإجازات الرسمية وأسماؤها
holidays = get(
    "/v1/calendars/holidays/USA/2026"
)["holidays"]
print(holidays[0]["date"], holidays[0]["name"])

تواريخ الإصدار في بايثون

اقرأ releases للحصول على تواريخ إصدار البيانات الاقتصادية في الدولة ونطاق التاريخ المطلوبين. لكل إصدار at وperiod وtopic وstatus. تحتوي استجابة 24 أكتوبر 2026 على 31 إصدارًا في نطاق نوفمبر 2026. يطبع المثال فترة أول إصدار ويقرأ حقل at الخاص به باستخدام .get() كما يفعل السكربت الكامل.

تواريخ إصدار البيانات الاقتصادية
releases = get(
    "/v1/economics/calendar",
    countries="USA",
    start_date="2026-11-01",
    end_date="2026-11-30",
    limit=100,
)["releases"]
print(releases[0]["period"], releases[0].get("at"))

البيانات الاقتصادية في بايثون

اقرأ observations للحصول على فترات CPI وقيمه، مع استخدام start لطلب الملاحظات ابتداءً من فترة معينة. مؤشر CPI لشهر سبتمبر 2026 هو 336.940 في استجابة 24 أكتوبر 2026. لكل ملاحظة period وvalue؛ ويقرأ هذا المثال الحقلين من آخر صف معاد. تشمل البيانات الاقتصادية في Narwhal أيضًا التضخم والناتج المحلي الإجمالي والعوائد.

ملاحظات CPI
cpi = get(
    "/v1/economics/USA/cpi/observations", start="2025-09"
)["observations"]
print(cpi[-1]["period"], cpi[-1]["value"])

أسعار السلع الفورية في بايثون

اقرأ price للحصول على سعر Brent الفوري بالدولار الأمريكي (USD). تعطي استجابة 24 أكتوبر 2026 سعر Brent عند 116.8809 دولارًا للبرميل. يسند المثال هذا الحقل إلى brent ويطبعه مع تسمية. تشمل رموز السلع الفورية مثلًا XAU وXAG وXPT وXPD وXCU وBRENT وWTI؛ ويستخدم هذا الطلب BRENT.

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

أسعار الصرف في بايثون

اقرأ rates للحصول على أسعار العملات المطلوبة مقابل USD. لكل صف currency وrate، ويحولهما المثال إلى قاموس. تعطي استجابة 24 أكتوبر 2026 سعر USD/EUR عند 0.89342 وUSD/IDR عند 18107.8، وكلاهما عند إغلاق 23 أكتوبر 2026. يطلب الاستدعاء EUR وIDR معًا عبر المعامل currencies.

أسعار صرف USD
fx = get(
    "/v1/fx/rates/USD", currencies="EUR,IDR"
)["rates"]
print({r["currency"]: r["rate"] for r in fx})

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

اقرأ meetings للحصول على مسار سياسة الاحتياطي الفيدرالي (Federal Reserve). لكل اجتماع resolves_at وp_cut وp_hold وp_hike. تعطي استجابة 24 أكتوبر 2026 احتمال تثبيت قدره 0.9188 لاجتماع 28 أكتوبر 2026. يطبع هذا المثال جزء التاريخ من resolves_at وقيمة p_hold للاجتماع الأول، مستخدمًا الحقول نفسها المستخدمة في السكربت الكامل.

احتمالات اجتماعات الاحتياطي الفيدرالي (Federal Reserve)
fed = get(
    "/v1/predictions/policy-paths/federal-reserve"
)["meetings"]
print(fed[0]["resolves_at"][:10], fed[0]["p_hold"])

لماذا أحصل على 401؟

رأس Authorization غير موجود أو أن متغير البيئة فارغ. اطبع ما إذا كانت بايثون ترى قيمة لـ NARWHAL_API_KEY باستخدام bool(os.environ.get('NARWHAL_API_KEY')). تبني الدالة المساعدة رأسها من هذا المتغير، لذا اضبطه في البيئة التي يعمل فيها السكربت. الرأس المتوقع هو Authorization: Bearer YOUR_KEY وتأتي قيمة المفتاح من متغير البيئة. وفي الجلب المجدول، ابحث عن المتغير الفارغ في بيئة المهمة.

كيف أحوّل قائمة صفوف إلى جدول؟

استخدم pandas.DataFrame(rows) مع قائمة الصفوف التي تريد تحويلها إلى جدول. في استدعاء الإجازات الرسمية تكون القائمة holidays؛ وفي تواريخ الإصدار تكون releases. راجع شرح pandas للتعامل مع الجدول بعد قراءة صفوف الاستجابة. وحقول observations الخاصة بـ CPI وrates للصرف وmeetings للتنبؤات هي أيضًا قوائم صفوف. اختر حقل الاستجابة في بايثون قبل تمرير صفوفه إلى pandas.DataFrame(rows).

نُشر في .

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