استخدم R وNarwhal API لجلب الإجازات الرسمية وتواريخ الإصدار والبيانات الاقتصادية وأسعار السلع الفورية وأسعار الصرف واحتمالات أسواق التنبؤ بمفتاح API واحد. احتفظ بالمفتاح في .Renviron، واقرأ الاستجابات باستخدام httr2، واستخدم الحقول المعادة في سكربت R.
ما الذي ستعدّه
يمكن لـ R استدعاء Narwhal REST API عبر httr2 وقراءة استجابة JSON. ستحصل على دالة مساعدة قابلة لإعادة الاستخدام باسم narwhal()، واستدعاءات لمجالات البيانات الستة كلها، وسكربت يمكنك جدولته باسم pull.R. تستخدم الدالة المساعدة https://api.narwhalapi.com عنوانَ قاعدة وتضيف المسار ومعاملات الاستعلام لكل طلب. تشمل البيانات الاقتصادية في Narwhal مؤشر CPI والتضخم والناتج المحلي الإجمالي والعوائد؛ ويختار استدعاء البيانات الاقتصادية هنا ملاحظات CPI.
تحتفظ الأمثلة بكل مجال استجابة في كائن R مستقل. تأتي الإجازات الرسمية وتواريخ الإصدار قوائم سجلات، وكذلك ملاحظات CPI وأسعار الصرف واجتماعات أسواق التنبؤ. ويقرأ مثال السلع حقلًا واحدًا هو price. تذكّر أشكال الاستجابة هذه عند اختيار الحقول للحسابات أو عند تحويل السجلات إلى إطار بيانات.
اضبط مفتاح API الخاص بك
- أنشئ مفتاحًا مجانيًا أنشئ مفتاحك من narwhalapi.com/signup. يستخدم Narwhal حسابًا واحدًا ومفتاح API واحدًا عبر واجهات البيانات التابعة له.
- احفظ المفتاح في .Renviron ضع مفتاحك في
.Renvironباسم متغير البيئةNARWHAL_API_KEY. استبدل العنصر النائب بمفتاحك وأبقِ المفتاح خارجpull.R. يجب أن يطابق اسم المتغير الاسم الممرَّر إلىSys.getenv()في الدالة المساعدة. العلامة...في مثال متغير البيئة هي العنصر النائب لمفتاحك.NARWHAL_API_KEY=... - ثبّت حزم R ثبّت
httr2وjsonliteبالأمر الموضح هنا. تستخدم الدالة المساعدة للطلباتhttr2لإرسال طلبات GET وقراءة أجسام JSON الخاصة بها.install.packages(c("httr2", "jsonlite"))
اسحب البيانات بالكود
احفظ هذه الشيفرة في pull.R. تقرأ الدالة المساعدة NARWHAL_API_KEY باستخدام Sys.getenv() وترسل المفتاح رمزَ Bearer، مستخدمةً الرأس Authorization: Bearer YOUR_KEY. يوفر كل استدعاء مسارًا؛ وتوفر الاستدعاءات التي تحتاج إلى نطاق تواريخ أو اختيار عملات معاملات استعلام أيضًا. استخدم الدالة المساعدة نفسها في أمثلة المجالات التالية.
library(httr2)
narwhal <- function(path, ...) {
request("https://api.narwhalapi.com") |>
req_url_path_append(path) |>
req_url_query(...) |>
req_auth_bearer_token(Sys.getenv("NARWHAL_API_KEY")) |>
req_perform() |>
resp_body_json()
}
holidays <- narwhal("v1/calendars/holidays/USA/2026")$holidays
releases <- narwhal("v1/economics/calendar", countries = "USA",
start_date = "2026-11-01", end_date = "2026-11-30",
limit = 100)$releases
cpi <- narwhal("v1/economics/USA/cpi/observations", start = "2025-09")$observations
brent <- as.numeric(narwhal("v1/commodities/spot/BRENT/USD")$price)
fx <- narwhal("v1/fx/rates/USD", currencies = "EUR,IDR")$rates
fed <- narwhal("v1/predictions/policy-paths/federal-reserve")$meetings
cpi_values <- vapply(cpi, function(row) as.numeric(row$value), numeric(1))
n <- length(cpi_values)
mom <- cpi_values[n] / cpi_values[n - 1] - 1
print(round(mom * 100, 2)) # month-on-month change in percent
داخل الدالة المساعدة، يضيف req_url_path_append(path) مسار نقطة النهاية إلى عنوان القاعدة، ويضيف req_url_query(...) وسائط الاستعلام. ويأخذ req_auth_bearer_token() المفتاح المقروء من البيئة. ثم يستخدم الاستدعاء req_perform() وresp_body_json() لإعادة جسم الاستجابة إلى R. اقرأ الحقل المسمى من ذلك الجسم باستخدام $، كما يفعل كل مثال للمجالات.
يقرأ حساب CPI قيمة value لكل ملاحظة رقمًا. ويقسم القيمة الأخيرة في القائمة المعادة على القيمة التي قبلها، ثم يطرح واحدًا، ويطبع التغير الشهري بالنسبة المئوية. يبقى الحقل period مع كل ملاحظة عند استخدام قيمتها خارج الحساب.
لتحويل قائمة سجلات إلى إطار بيانات، استخدم dplyr::bind_rows أو do.call(rbind, lapply(x, as.data.frame)). هنا x هو القائمة التي تريد تحويلها، مثل holidays أو releases أو cpi. اختر حقل الاستجابة أولًا ليستقبل التحويل سجلات ذلك المجال.
يبقى المسار ووسائط الاستعلام منفصلين في هذه الاستدعاءات. في CPI، يختار المسار ملاحظات CPI للولايات المتحدة ويوفر start فترة البداية. وفي الصرف، يختار المسار USD ويوفر currencies العملتين EUR وIDR. يستخدم الاستدعاءان عنوان القاعدة في الدالة المساعدة ومصادقة Bearer.
جدولة الجلب اليومي
جدول تشغيل Rscript pull.R مرة في اليوم باستخدام cron أو Windows Task Scheduler. يمكن لحزمة cronR كتابة سطر cron نيابة عنك. أبقِ الطلبات التي تريدها في pull.R مع الدالة المساعدة والبحث عن متغير البيئة، ليستدعي الأمر المجدول السكربت نفسه.
Rscript pull.Rتبقى التواريخ واختيارات العملات كما هي مكتوبة في السكربت. فمثلًا، يطلب استدعاء تواريخ الإصدار شهر نوفمبر 2026، ويطلب استدعاء الإجازات الرسمية إجازات الولايات المتحدة لعام 2026. ويكرر الجدول اليومي هذه الطلبات. راجع جدولة جلب البيانات يوميًا لمعرفة مسار الجدولة.
الإجازات الرسمية في R
اقرأ الإجازات الرسمية للولايات المتحدة لعام 2026 من holidays. لكل سجل date وname، فأبقِ الحقلين معًا عند تحويل السجلات إلى إطار بيانات. يستخدم هذا الاستدعاء الدولة والسنة في المسار ويقرأ قائمة الإجازات من الاستجابة.
response <- narwhal("v1/calendars/holidays/USA/2026")
holidays <- response$holidays
holidaysتواريخ الإصدار في R
اقرأ تواريخ إصدار البيانات الاقتصادية للولايات المتحدة لشهر نوفمبر 2026 من releases. يتضمن الطلب الدولة وتاريخ البداية وتاريخ النهاية والحد الأقصى. لكل إصدار at وperiod وtopic وstatus؛ أبقِ هذه الحقول معًا عند استخدام سجلات الإصدار في R.
response <- narwhal("v1/economics/calendar", countries = "USA",
start_date = "2026-11-01", end_date = "2026-11-30", limit = 100)
releases <- response$releases
releasesالبيانات الاقتصادية في R
اقرأ ملاحظات CPI للولايات المتحدة بفترة بداية سبتمبر 2025 من observations. لكل ملاحظة period وvalue. يستخدم مثال الدالة المساعدة هذه القيم لحساب التغير الشهري؛ أبقِ الفترة بجانب القيمة عند عرض ملاحظة أو نتيجة مشتقة منها.
response <- narwhal("v1/economics/USA/cpi/observations", start = "2025-09")
cpi <- response$observations
cpiأسعار السلع الفورية في R
اقرأ سعر Brent الفوري بالدولار الأمريكي (USD) من price. يختار هذا الاستدعاء السلعة والعملة في المسار، ثم يحوّل السعر المعاد باستخدام as.numeric(). تشمل رموز السلع الفورية مثلًا XAU وXAG وXPT وXPD وXCU وBRENT وWTI.
response <- narwhal("v1/commodities/spot/BRENT/USD")
brent <- as.numeric(response$price)
brentأسعار الصرف في R
اقرأ أسعار الصرف مع USD عملةً أساسية وEUR وIDR عملتين مطلوبتين. حقل الاستجابة هو rates، ولكل سجل currency وrate. أبقِ حقل العملة مع سعره عند تحويل القائمة إلى إطار بيانات.
response <- narwhal("v1/fx/rates/USD", currencies = "EUR,IDR")
fx <- response$rates
fxاحتمالات أسواق التنبؤ في R
اقرأ استجابة مسار سياسة الاحتياطي الفيدرالي (Federal Reserve) من meetings. لكل اجتماع resolves_at وp_cut وp_hold وp_hike. أبقِ حقول الاجتماع معًا عند قراءة الاحتمالات في R، مع وقت الحسم بجانب حقول الخفض والتثبيت والرفع.
response <- narwhal("v1/predictions/policy-paths/federal-reserve")
fed <- response$meetings
fedأين أضع المفتاح؟
ضع المفتاح في .Renviron، ولا تضعه أبدًا في السكربت. تقرأ الدالة المساعدة Sys.getenv("NARWHAL_API_KEY") لمصادقة Bearer. يشترك REST وMCP في المفتاح، لذا تستخدم الحساب والمفتاح نفسيهما عند الوصول إلى Narwhal بأي من الطريقتين.
لماذا يكون price سلسلة نصية؟
تُعاد القيم العشرية سلاسل نصية. استخدم as.numeric() لتحويل price إلى رقم لحسابات R، كما يفعل مثال Brent. ويحوّل حساب CPI أيضًا قيمة value لكل ملاحظة قبل قسمة القيم لحساب التغير.
نُشر في .