تحقّق مما إذا كان تاريخ ما إجازة رسمية

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

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

1. احصل على مفتاح API الخاص بك أنشئ مفتاحًا مجانيًا واحفظه في متغير البيئة NARWHAL_API_KEY. أرسله بصيغة Authorization: Bearer YOUR_KEY؛ تستخدم أوامر curl متغير البيئة هذا في ترويسة التفويض.
2. اطلب التاريخ للدولة استخدم GET /v1/calendars/holidays/{country}/on/{date} مع الدولة والتاريخ اللذين تريدهما. يطلب هذا الطلب العطلات في المملكة المتحدة في 28 ديسمبر 2026.
   curl، عطلة في تاريخ واحد

   curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
     "https://api.narwhalapi.com/v1/calendars/holidays/GBR/on/2026-12-28"

3. اقرأ قائمة العطلات تعني قائمة holidays الفارغة أن التاريخ المطلوب ليس عطلة هناك. وتضم القائمة غير الفارغة سجلات العطلات لذلك التاريخ، لذا استخدم نطاقاتها وتقسيماتها الإدارية لتحديد مدى مطابقتها لتقويم العطلات الذي تحتاجه.
4. ابحث عن عطلة في تاريخ محدد أو بعده استخدم نقطة نهاية العطلة التالية عندما تحتاج إلى عطلة بدءًا من تاريخ محدد، بما في ذلك التاريخ نفسه. بالنسبة إلى الولايات المتحدة، يعيد from_date=2026-10-24 يوم المحاربين القدامى في 11 نوفمبر 2026 ضمن holiday.
   curl، عطلة في تاريخ محدد أو بعده

   curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
     "https://api.narwhalapi.com/v1/calendars/holidays/USA/next?from_date=2026-10-24"

إذا أعاد الطلب خطأ، فاقرأ استجابة application/problem+json. تصف حقول status وcode وdetail الخطأ، ويحدد request_id الطلب. استخدم قائمة العطلات من استجابة ناجحة للإجابة عن السؤال المتعلق بالتاريخ؛ فاستجابة الخطأ لا تعطيك نتيجة العطلات لذلك التاريخ.

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

ابحث عن الدولة في تقاويم العطلات من Narwhal (الإنجليزية) إذا أردت معرفة التاريخ دون طلب إلى واجهة API. ابدأ بالدولة التي تحتاج إلى تقويمها: يستخدم مثال أسبوع عيد الميلاد نتائج منفصلة للولايات المتحدة والمملكة المتحدة، وقد تكون السجلات الإقليمية داخل الدولة مهمة أيضًا.

في Excel أو Sheets، استخدم عمودًا لتواريخ العطلات باسم Holidays وضع التاريخ المراد اختباره في A2. تتحقق الصيغة من وجود ذلك التاريخ في عمود العطلات. استخدم قائمة العطلات للدولة التي تتحقق منها، لأن الصيغة تختبر وجود التاريخ ضمن التواريخ التي تزودها بها.

=COUNTIF(Holidays, A2)>0

باستخدام قائمة عطلات الولايات المتحدة، تعيد الصيغة TRUE لتاريخ 25 ديسمبر 2026 وFALSE لتاريخ 24 ديسمبر 2026. تعتمد هذه النتائج على تواريخ العطلات في Holidays؛ ولا تطلب الصيغة نفسها تقويم دولة من واجهة API.

لا يحتاج اختبار وجود التاريخ إلا إلى معرفة ما إذا كان التاريخ مدرجًا في القائمة التي اخترتها. إذا اشتركت سجلات إقليمية في تاريخ واحد، تظل الصيغة قادرة على الإجابة عن هذا السؤال. لتحديد المنطقة التي ينطبق عليها سجل ما، اقرأ تقسيماته الإدارية في استجابة واجهة API قبل استخدام تاريخه في قائمتك.

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

لاستخدام قائمة السنة، اتبع خطوات إضافة فحص للعطلات إلى شيفرتك. تجيب نقطة نهاية التاريخ عن سؤال يتعلق بتاريخ محدد، بينما تقبل نقطة نهاية العطلة التالية تاريخ بداية وتعيد تاريخ عطلة. إذا كان سؤالك هو ما إذا كان تاريخ معين عطلة، فأبقِ ذلك التاريخ في الطلب. وإذا كان سؤالك هو أي عطلة تقع فيه أو بعده، فمرره بوصفه from_date.

لماذا تسرد الاستجابة العطلة نفسها أكثر من مرة؟

عندما تختلف العطلات حسب المنطقة، تعيد واجهة API سجلًا لكل مجموعة من التقسيمات الإدارية. وبالنسبة إلى عطلة يوم الصناديق التي يُحتفل بها في موعد بديل في 28 ديسمبر 2026 في المملكة المتحدة، تعيد ثلاثة سجلات: إنجلترا وويلز معًا، وأيرلندا الشمالية، واسكتلندا.

رموز التقسيمات الإدارية هي GB-ENG وGB-WLS للسجل المشترك، وGB-NIR لأيرلندا الشمالية، وGB-SCT لاسكتلندا. لكل سجل نطاق bank وقيمة observed: true. هذه سجلات إقليمية لتاريخ العطلة نفسه، لذا اقرأ مجموعة التقسيمات الإدارية إلى جانب الاسم.

ماذا تعني observed: true؟

تعني أن التاريخ هو اليوم البديل عندما تقع العطلة في عطلة نهاية الأسبوع. يوافق يوم الصناديق، 26 ديسمبر 2026، يوم السبت، لذا تكون العطلة المصرفية يوم الاثنين 28 ديسمبر 2026.

في هذا المثال، استخدم التاريخ البديل للعطلة المصرفية عند اختبار وجوده في تقويم العطلات المصرفية. يوضح حقل observed سبب اختلاف التاريخ المُعاد عن التاريخ التقويمي للعطلة؛ وينتمي التاريخان إلى مثال يوم الصناديق نفسه.

كيف أستبعد أيام الإجازة الجماعية؟

مرر scope=national_public لاستبعاد أيام الإجازة الجماعية في إندونيسيا من النتائج. تُدرج إندونيسيا أيام cuti bersama بنطاق خاص بها هو collective_leave، لذا قد يتضمن الطلب هذه الأيام إذا لم يستخدم ذلك المرشح.

يقصر مرشح scope الاختياري النتائج على نطاق واحد. من أمثلة النطاقات المتاحة national_public وbank وfederal_government وcollective_leave. اختر النطاق الذي يطابق التقويم الذي تحتاجه قبل تفسير سجلات العطلات المُعادة.

مثال تطبيقي: أسبوع عيد الميلاد 2026 في الولايات المتحدة والمملكة المتحدة

ابدأ بتاريخ 24 ديسمبر 2026 في الولايات المتحدة. تشير قائمته الفارغة إلى أنه ليس عطلة. ثم اختبر 25 ديسمبر 2026 للدولة نفسها: يظهر عيد الميلاد بنطاق federal_government، مما يعطي نتيجة إيجابية لذلك التقويم.

بالنسبة إلى المملكة المتحدة، اختبر 25 ديسمبر 2026 واقرأ سجل عيد الميلاد بنطاق bank. ثم اختبر 28 ديسمبر 2026 للاطّلاع على سجلات الموعد البديل ليوم الصناديق. احتفظ بالدولة والتاريخ والنطاق معًا عند تسجيل كل نتيجة.