أضف فحصًا للعطلات إلى شيفرتك

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

يعيد GET /v1/calendars/holidays/{country}/{year} السنة كاملة. خزّن سلاسل date المُعادة مؤقتًا حسب الدولة والسنة، بحيث تُجري المهمة التي تعالج آلاف التواريخ طلبًا واحدًا لكل دولة وسنة. احتفظ بالدولة والسنة معًا في ذاكرة التخزين المؤقت: يجب أن تطابق المجموعة المستخدمة التاريخ الذي تمرره إلى الدالة.

1. اضبط مفتاح API الخاص بك احصل على مفتاح مجاني واحتفظ به في متغير البيئة NARWHAL_API_KEY. تقرأ البرامج ذلك المتغير وترسل المفتاح بصيغة Authorization: Bearer YOUR_KEY إلى https://api.narwhalapi.com.
2. استخدم دالة Python التي تعتمد على التخزين المؤقت تخزّن الدالة سلاسل العطلات في frozenset وتستخدم الدولة والسنة وسيطتين للتخزين المؤقت. استدعِ is_business_day باستخدام date في Python؛ فدولتها الافتراضية هي USA، وتعيد False لعطلة نهاية الأسبوع قبل البحث عن العطلة.
   Python، فحص يوم العمل باستخدام التخزين المؤقت

   import os
   from datetime import date
   from functools import lru_cache
   import requests
   
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   
   
   @lru_cache(maxsize=None)
   def holiday_dates(country: str, year: int) -> frozenset[str]:
       r = requests.get(
           f"https://api.narwhalapi.com/v1/calendars/holidays/{country}/{year}",
           headers=HEADERS,
           timeout=10,
       )
       r.raise_for_status()
       return frozenset(h["date"] for h in r.json()["holidays"])
   
   
   def is_business_day(day: date, country: str = "USA") -> bool:
       return day.weekday() < 5 and day.isoformat() not in holiday_dates(country, day.year)
   
   
   for d in (date(2026, 11, 26), date(2026, 11, 27), date(2026, 11, 28)):
       print(d, d.strftime("%a"), is_business_day(d))

3. استخدم دالة JavaScript في تطبيقك في JavaScript، تخزّن الخريطة مجموعة لكل دولة وسنة، وتقبل الدالة سلسلة تاريخ بصيغة ISO. مرر الدولة عندما تحتاج إلى تقويم غير التقويم الافتراضي USA؛ وتُعالَج حالة الاستجابة قبل إدخال التواريخ في ذاكرة التخزين المؤقت.
   JavaScript (Node 18+)، الفحص نفسه

   const headers = { Authorization: `Bearer ${process.env.NARWHAL_API_KEY}` };
   const cache = new Map();
   
   async function holidayDates(country, year) {
     const key = `${country}-${year}`;
     if (!cache.has(key)) {
       const res = await fetch(
         `https://api.narwhalapi.com/v1/calendars/holidays/${country}/${year}`,
         { headers },
       );
       if (!res.ok) throw new Error(`Narwhal ${res.status}`);
       cache.set(key, new Set((await res.json()).holidays.map((h) => h.date)));
     }
     return cache.get(key);
   }
   
   export async function isBusinessDay(isoDate, country = "USA") {
     const day = new Date(`${isoDate}T12:00:00Z`).getUTCDay();
     if (day === 0 || day === 6) return false;
     return !(await holidayDates(country, Number(isoDate.slice(0, 4)))).has(isoDate);
   }
   
   console.log(
     await isBusinessDay("2026-11-26"),
     await isBusinessDay("2026-11-27"),
     await isBusinessDay("2026-11-28"),
   );

تتضمن خطة Free عددًا قدره 5,000 طلب شهريًا، لذا تهم إعادة استخدام المجموعة السنوية عندما تعالج المهمة تواريخ كثيرة.

تخص ذاكرة التخزين المؤقت في Python الدالة holiday_dates؛ أما في JavaScript فهي Map الموجودة خارج الدالة. يحتفظ الاثنان بتواريخ العطلات في الذاكرة لإعادة استخدامها. أضف جدول التحديث والتخزين في ملف أو قاعدة بيانات عندما يحتاج تطبيقك إليهما. يتطلب تحديث السنة الحالية شهريًا والاحتفاظ بالتواريخ بعد إعادة التشغيل إضافة هاتين الإمكانيتين إلى البحث المعتمد على التخزين المؤقت.

نفّذ ذلك في جدول بيانات أو دون شيفرة

احتفظ بعمود Holidays في علامة تبويب مستقلة واستخدم Holidays اسمًا للنطاق في الصيغة. ضع التاريخ الذي تريد تقييمه في A2. تجمع الصيغة بين اختبار يوم الأسبوع وحساب مرات ظهور ذلك التاريخ في نطاق العطلات، لذا تستخدم الورقة قاعدة يوم العمل نفسها التي تستخدمها البرامج. يجب أن يحتوي عمود العطلات على تواريخ الدولة والسنة اللتين تقيّمهما، كما تفعل ذاكرة التخزين المؤقت لواجهة API. أبقِ ذلك العمود متاحًا عند استخدام الصيغة لتواريخ أخرى.

=AND(WEEKDAY(A2,2)<6, COUNTIF(Holidays, A2)=0)

يعيد أحد أيام الأسبوع TRUE فقط عندما لا يحتوي نطاق Holidays على تاريخ مطابق. ويعيد السبت أو الأحد FALSE حتى إن لم يكن مدرجًا في ذلك النطاق. تناسب هذه الطريقة فريقًا يعدّل تواريخ العطلات يدويًا: يحتفظ العمود بالتواريخ، بينما تحدد الصيغة ما إذا كان التاريخ في A2 يوم عمل.

متى تستخدم كل خيار

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

كم من الوقت ينبغي أن أخزّن تواريخ العطلات مؤقتًا؟

حدّث السنة الحالية شهريًا واجلب السنة التالية عند ظهورها. نادرًا ما تتغير تقاويم العطلات، لذا يمكن إعادة استخدام المجموعة السنوية بين التحديثات. إذا كان تطبيقك يُعاد تشغيله كثيرًا، فاحفظ تلك المجموعة مع سنتها في ملف أو جدول قاعدة بيانات، ثم حدّثها سنويًا أيضًا.

لا تخزّن استجابة فاشلة مؤقتًا. يعالج البرنامجان الاستجابة غير الناجحة قبل تخزين تواريخ عطلاتها. يمكن الإبلاغ عن مراجعات التقويم عبر الحدث holiday.calendar.revised في خطاف الويب والتدفق على خطتي Basic أو Pro.

ما المنطقة الزمنية التي ينبغي أن يعتمدها التاريخ؟

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

تقبل دالة Python قيمة date. وتقبل دالة JavaScript سلسلة تاريخ بصيغة ISO وتستخدم سنتها لاختيار مجموعة العطلات. لا يقبل أي من الاستدعاءين وسيطة للمنطقة الزمنية للسوق.

ماذا لو لم تُنشر السنة بعد؟

تعيد واجهة API الخطأ 404 calendar_not_published؛ فاعتمد عندئذٍ على عطلات نهاية الأسبوع فقط وسجّل ذلك. في هذا البديل، يظل السبت والأحد يومين لا يُعدّان يومي عمل، بينما تجتاز بقية أيام الأسبوع الفحص دون البحث عن العطلات. وتعتمد نتيجة يوم الأسبوع حينها على قاعدة عطلة نهاية الأسبوع وحدها، لأن تقويم العطلات غير متاح.

تُطلق الدالتان خطأ عند تلقي استجابة غير ناجحة. أضف البديل الذي يعتمد على عطلات نهاية الأسبوع فقط في الموضع الذي يعالج فيه تطبيقك ذلك الخطأ، ولا تُدخل استجابة التقويم غير المنشور في ذاكرة التخزين المؤقت للعطلات. راجع أخطاء واجهة API للاطّلاع على مرجع الأخطاء.

مثال تطبيقي: أسبوع عيد الشكر 2026

ابدأ بيوم الخميس 26 نوفمبر 2026 وتقويم USA لعام 2026. إنه أحد أيام الأسبوع، لذا يحدد اختبار وجود التاريخ ضمن العطلات النتيجة. يوافق التاريخ عيد الشكر في الولايات المتحدة، فتكون نتيجة يوم العمل False.

انتقل إلى الجمعة 27 نوفمبر 2026. يجتاز اختبار يوم الأسبوع ولا يرد في مجموعة العطلات، لذا تكون النتيجة True. لا يجتاز السبت 28 نوفمبر 2026 اختبار يوم الأسبوع ويعيد False دون البحث عن العطلات.

2026-11-26 Thu False
2026-11-27 Fri True
2026-11-28 Sat False

false true false