استخدام Narwhal API مع Looker Studio API

يمكنك رسم مخططات لإجازات Narwhal الرسمية ومواعيد الإصدار والبيانات الاقتصادية والسلع وأسعار الصرف والتوقعات في Looker Studio عبر Google Sheets. يسحب Apps Script البيانات إلى الجدول باستخدام مفتاح API، ويستخدم Looker Studio ذلك الجدول مصدرًا للبيانات. ويضيف مشغّل يومي صفوفًا لخام Brent وأسعار الصرف واحتمالات أسواق التنبؤ.

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

يتصل Looker Studio بجدول Google Sheets يحتوي على بيانات Narwhal. ستستخدم علامة تبويب واحدة لكل مجال، مع Apps Script لسحب استجابات API إلى علامات التبويب هذه. يستخدم البرنامج النصي اليومي علامات تبويب بالأسماء Brent وFX وFed؛ أما الإجازات الرسمية ومواعيد الإصدار ومؤشر CPI فلكل منها علامة تبويب خاصة عبر درس Google Sheets. تتضمن البيانات الاقتصادية في Narwhal مؤشر CPI والتضخم والناتج المحلي الإجمالي (GDP) والعوائد، وطلب CPI هنا هو العيّنة الاقتصادية للجدول.

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

  1. أنشئ مفتاحًا مجانيًا أنشئ حسابك على narwhalapi.com/signup واحصل على مفتاح API. يستخدم Narwhal حسابًا واحدًا ومفتاحًا واحدًا لجميع واجهات البيانات، ويتشارك REST وMCP المفتاح نفسه.
  2. تخزين المفتاح في Apps Script في مشروع Apps Script الخاص بجدول Google Sheets، خزّن المفتاح في خصائص البرنامج النصي (Script Properties) تحت الاسم NARWHAL_API_KEY. يقرأ البرنامج هذه الخاصية عند إرسال أي طلب؛ لذا لا تضع المفتاح داخل الشيفرة التي تلصقها.
  3. تجهيز علامات تبويب الجدول أنشئ علامات التبويب Brent وFX وFed التي تستخدمها الدالة appendDaily، مع علامة تبويب منفصلة لكل مجال آخر تريد سحبه. استخدم أسماء علامات التبويب نفسها الواردة في البرنامج النصي حتى يُكتب كل صف في علامة التبويب المقصودة.

ربط الجدول بـ Looker Studio

  1. تعبئة الجدول لتحميل بياناتك استخدم إعداد Apps Script الوارد في درس Google Sheets. تملأ الدالة pullAll() فيه علامات تبويب الإجازات الرسمية ومواعيد الإصدار ومؤشر CPI؛ واستخدم appendDaily هنا للصفوف اليومية.
  2. ربط الجدول كمصدر للبيانات في Looker Studio، اربط جدول Google Sheets كمصدر للبيانات. استخدم علامة التبويب الخاصة بالمجال الذي تريد رسمه، مع إبقاء كل مجال في علامة تبويب مستقلة.
  3. إنشاء المخطط من الجدول استخدم البيانات الموجودة في علامة التبويب هذه لإنشاء المخطط. وفي السلاسل الزمنية، احتفظ بالصفوف من عمليات السحب السابقة وأضف صفًا جديدًا عند كل سحب مجدول بدلًا من مسح علامة التبويب.

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

أضف هذا الـ Apps Script إلى جدول Google Sheets الذي يضم علامات تبويب بياناتك. يقرأ NARWHAL_API_KEY من خصائص البرنامج النصي ويرسله في ترويسة Authorization: Bearer YOUR_KEY إلى https://api.narwhalapi.com. يتضمن كل صف مضاف تاريخ السحب، وتحتوي الأعمدة الباقية على قيم ذلك المجال. تحتوي صفوف Brent على السعر الفوري، وصفوف FX على العملة وسعر الصرف، أما صفوف Fed فتحتوي على تاريخ حسم الاجتماع واحتمال الإبقاء على الفائدة.

Apps Script، إضافة صف واحد كل يوم
function appendDaily() {
  const key = PropertiesService.getScriptProperties().getProperty("NARWHAL_API_KEY");
  const get = (path) =>
    JSON.parse(
      UrlFetchApp.fetch("https://api.narwhalapi.com" + path, {
        headers: { Authorization: "Bearer " + key },
      }).getContentText(),
    );
  const book = SpreadsheetApp.getActiveSpreadsheet();
  const brent = get("/v1/commodities/spot/BRENT/USD");
  book.getSheetByName("Brent").appendRow([new Date(), Number(brent.price)]);
  const fx = get("/v1/fx/rates/USD?currencies=EUR,IDR").rates;
  fx.forEach((rate) =>
    book.getSheetByName("FX").appendRow([new Date(), rate.currency, Number(rate.rate)]),
  );
  const hold = get("/v1/predictions/policy-paths/federal-reserve").meetings[0];
  book
    .getSheetByName("Fed")
    .appendRow([new Date(), hold.resolves_at, Number(hold.p_hold)]);
}
// Holidays, releases and CPI change rarely: fill their tabs with pullAll() from
// the Google Sheets tutorial.

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

اضبط في Apps Script مشغّلًا يوميًا مبنيًا على الوقت لتشغيل appendDaily. تضيف الدالة أسعار Brent إلى Brent، وأسعار العملات إلى FX، واحتمال الإبقاء على الفائدة في أول اجتماع إلى Fed. ويقرأ Looker Studio الجدول لرسم المخطط.

احتفظ بالصفوف السابقة عندما تريد سلسلة زمنية؛ فمسح علامة التبويب سيزيل عمليات السحب السابقة التي يستخدمها المخطط لعرض تاريخه. تتغير الإجازات الرسمية ومواعيد الإصدار ومؤشر CPI نادرًا، لذا املأ علامات تبويبها بالدالة pullAll() من درس Google Sheets.

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

اسحب الإجازات الرسمية في الولايات المتحدة لعام 2026 إلى علامة تبويب الإجازات. يعيد الطلب holidays، ولكل عنصر فيه date وname. في إعداد Google Sheets استخدم pullAll() لملء علامة التبويب هذه. اربط Looker Studio بعلامة تبويب الإجازات عندما تريد أن يقرأ المخطط تواريخ الإجازات وأسماءها من الجدول.

قراءة الإجازات الرسمية
const key = PropertiesService.getScriptProperties().getProperty("NARWHAL_API_KEY");
const get = (path) =>
  JSON.parse(
    UrlFetchApp.fetch("https://api.narwhalapi.com" + path, {
      headers: { Authorization: "Bearer " + key },
    }).getContentText(),
  );
const holidays = get("/v1/calendars/holidays/USA/2026").holidays;

مواعيد الإصدار في Looker Studio

اسحب مواعيد الإصدار في الولايات المتحدة لشهر نوفمبر 2026 إلى علامة تبويب مواعيد الإصدار. اضبط countries=USA واستخدم start_date وend_date لتحديد النطاق المطلوب، مع limit=100 كما في هذا الطلب. اقرأ releases؛ ولكل عنصر فيه at وperiod وtopic وstatus. استخدم pullAll() من درس Google Sheets لملء علامة التبويب هذه ببيانات الإصدار.

قراءة مواعيد الإصدار
const key = PropertiesService.getScriptProperties().getProperty("NARWHAL_API_KEY");
const get = (path) =>
  JSON.parse(
    UrlFetchApp.fetch("https://api.narwhalapi.com" + path, {
      headers: { Authorization: "Bearer " + key },
    }).getContentText(),
  );
const releases = get(
  "/v1/economics/calendar?countries=USA&start_date=2026-11-01" +
    "&end_date=2026-11-30&limit=100",
).releases;

البيانات الاقتصادية في Looker Studio

استخدم طلب ملاحظات CPI للولايات المتحدة بدءًا من سبتمبر 2025. اقرأ observations، ثم استخدم period وvalue لكل ملاحظة في علامة تبويب CPI. دالة pullAll() في درس Google Sheets هي الطريقة لملء علامة التبويب هذه إلى جانب الإجازات ومواعيد الإصدار. استخدم period الخاص بالملاحظة لسلسلة CPI بدلًا من التاريخ الذي سحب فيه Apps Script الاستجابة إلى الجدول.

اقرأ ملاحظات CPI
const key = PropertiesService.getScriptProperties().getProperty("NARWHAL_API_KEY");
const get = (path) =>
  JSON.parse(
    UrlFetchApp.fetch("https://api.narwhalapi.com" + path, {
      headers: { Authorization: "Bearer " + key },
    }).getContentText(),
  );
const observations = get(
  "/v1/economics/USA/cpi/observations?start=2025-09",
).observations;

السلع في Looker Studio

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

قراءة سعر Brent
const key = PropertiesService.getScriptProperties().getProperty("NARWHAL_API_KEY");
const get = (path) =>
  JSON.parse(
    UrlFetchApp.fetch("https://api.narwhalapi.com" + path, {
      headers: { Authorization: "Bearer " + key },
    }).getContentText(),
  );
const brent = get("/v1/commodities/spot/BRENT/USD");
brent.price;

أسعار الصرف في Looker Studio

اسحب أسعار صرف USD مقابل EUR وIDR إلى علامة تبويب FX. اقرأ المصفوفة rates من الاستجابة، ثم currency وrate لكل عنصر. يضيف البرنامج النصي اليومي سعر كل عملة مع تاريخ السحب، فتحتوي علامة التبويب على الصفوف اللازمة لسلسلتك الزمنية.

اقرأ أسعار الصرف
const key = PropertiesService.getScriptProperties().getProperty("NARWHAL_API_KEY");
const get = (path) =>
  JSON.parse(
    UrlFetchApp.fetch("https://api.narwhalapi.com" + path, {
      headers: { Authorization: "Bearer " + key },
    }).getContentText(),
  );
const rates = get("/v1/fx/rates/USD?currencies=EUR,IDR").rates;

التوقعات في Looker Studio

اسحب استجابة مسار سياسة الاحتياطي الفيدرالي واقرأ meetings. لكل اجتماع resolves_at وp_cut وp_hold وp_hike. يستخدم البرنامج النصي اليومي الاجتماع الأول ويضيف تاريخ حسمه واحتمال الإبقاء على الفائدة مع تاريخ السحب إلى Fed. ولرسم احتمالات الخفض أو الرفع، اقرأ p_cut أو p_hike من استجابة الاجتماع نفسه عند ملء علامة تبويب التوقعات.

قراءة اجتماعات التوقعات
const key = PropertiesService.getScriptProperties().getProperty("NARWHAL_API_KEY");
const get = (path) =>
  JSON.parse(
    UrlFetchApp.fetch("https://api.narwhalapi.com" + path, {
      headers: { Authorization: "Bearer " + key },
    }).getContentText(),
  );
const meetings = get("/v1/predictions/policy-paths/federal-reserve").meetings;

لماذا نمر عبر Google Sheets؟

لا تتضمن موصلات Looker Studio المدمجة حقلًا لترويسة الطلب. تستخدم طلبات Narwhal ترويسة Authorization، لذلك يتولى Apps Script إرسال الطلب ويضع بيانات الاستجابة في Google Sheets. ثم يتصل Looker Studio بالجدول بوصفه مصدر بياناته.

ما مدى حداثة المخطط؟

تعتمد حداثة المخطط على آخر تشغيل للمشغّل مضافًا إليه ذاكرة التخزين المؤقت للبيانات في Looker Studio نفسه. يحدد المشغّل اليومي موعد سحب Apps Script للبيانات إلى الجدول، كما تؤثر ذاكرة Looker Studio المؤقتة في موعد ظهور قيم الجدول في المخطط.

نُشر في .

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