مرجع واجهة API للعطلات الرسمية

الإصدار التجريبي العام المتاح حاليًا

استخدم مفتاح Narwhal API لسنوات الدول المنشورة أدناه. تشترك REST وMCP في التغطية والحصة نفسيهما. تعيد التغطية المفقودة خطأً صريحاً؛ وتظل الأمثلة توضيحية.

نظرة عامة على منتج الإجازات الرسمية · المنهجية ومراجعة المصدر

ثلاث عمليات

المرجع	نقطة نهاية GET	أداة MCP
اعرض الإجازات الرسمية	`/v1/calendars/holidays/{country}/{year}`	`calendars_list_holidays`
العطلات في تاريخ	`/v1/calendars/holidays/{country}/on/{date}`	`calendars_get_holidays_on_date`
الإجازة الرسمية التالية	`/v1/calendars/holidays/{country}/next?from_date={from_date}`	`calendars_get_next_holiday`

استخدم رموز الدول بالأحرف الكبيرة مثل IDN والتواريخ المدنية المحلية بالصيغة YYYY-MM-DD . معلمات country وdate/year مطلوبة. يحدّد المرشح الاختياري scope فئة العطلة. لا يوجد ترقيم صفحات أو مرشح للتقسيمات الفرعية.

كائن العطلة المشترك

حقل	النوع	المعنى
`date`	سلسلة نصية تمثل تاريخًا	تاريخ التقويم المحلي، وليس طابعًا زمنيًا للاستيعاب.
`name`	سلسلة نصية	الاسم الإنجليزي/المعروض، من 1 إلى 256 حرفًا.
`local_name`	سلسلة نصية	الاسم المحلي عند توفره، بطول 1–256 حرفًا. يُحذف عند عدم توفره.
`subdivision_codes`	مصفوفة من السلاسل النصية	رموز فريدة ومرتبة للتقسيمات الإدارية التابعة للدولة، مثل GB-SCT. تعني المصفوفة الفارغة أن العطلة تشمل الدولة بأكملها.
`scope`	سلسلة نصية	فئة العطلة، مثل national_public أو bank أو federal_government أو collective_leave.
`observed`	منطقي	حالة صريحة تبيّن ما إذا كان اليوم معتمدًا للاحتفال بالعطلة أو بديلًا عنها. تُحذف عندما تكون غير معروفة. الحالة غير المعروفة لا تعني false.

تتضمن كائنات العطلات دائمًا date وname وscope وsubdivision_codes. وتتضمن كل استجابة أيضًا بيانات التغطية مع scope وsubdivision_codes، حتى عندما تكون نتيجة البحث عن تاريخ فارغة. تبقى معرّفات الطلبات والحصة في الترويسات. لا تتضمن أجسام الاستجابات الناجحة عناوين URL للمصادر أو أوقات فحص استيعاب البيانات.

التغطية والحدود

تغطية APIالمنشورة · الدول والسنوات غير المدرجة كمتاحة تعيد أن التغطية غير متاحة.
الدولة	2026	2027	النطاق المنشور
`ARG`	متاح	غير متاح بعد	الإجازات الرسمية الوطنية
`AUS`	متاح	متاح	نيو ساوث ويلز فقط: الإجازات الرسمية والمصرفية الإقليمية
`AUT`	متاح	متاح	الإجازات الرسمية الوطنية
`BEL`	متاح	متاح	الإجازات الرسمية الوطنية
`BRA`	متاح	غير متاح بعد	الإجازات الرسمية للحكومة الاتحادية؛ مع استبعاد الإغلاقات الاختيارية والجزئية
`CAN`	متاح	متاح	الحد الأساسي المنصوص عليه قانونًا على مستوى الدولة لأصحاب العمل في القطاع الخاص الخاضعين للتنظيم الاتحادي؛ مع استبعاد تقاويم المقاطعات والخدمة العامة الاتحادية
`CHN`	متاح	غير متاح بعد	فترات العطلات الوطنية؛ تُستبعد أيام العمل التعويضية
`COL`	متاح	متاح	الإجازات الرسمية الوطنية
`CZE`	متاح	متاح	الإجازات الرسمية الوطنية؛ مع استبعاد الأيام ذات الأهمية وأيام الأحد العادية وإغلاقات أصحاب العمل
`DEU`	متاح	غير متاح بعد	الإجازات الرسمية المشتركة على مستوى الدولة؛ مع استبعاد العطلات الإضافية للولايات
`DNK`	متاح	متاح	أيام إغلاق Danmarks Nationalbank؛ ليست تقويمًا عامًا لعطلات العمل
`ESP`	متاح	غير متاح بعد	الإجازات الرسمية الوطنية
`EST`	متاح	متاح	الإجازات الرسمية الوطنية وأيام الراحة؛ مع استبعاد الأيام الوطنية ذات الأهمية وأيام العمل المختصرة
`FRA`	متاح	متاح	العطلات النظامية الوطنية العامة؛ مع استبعاد الإضافات الإقليمية
`GBR`	متاح	متاح	العطلات المصرفية في إنجلترا وويلز واسكتلندا وأيرلندا الشمالية
`HKG`	متاح	متاح	العطلات العامة في هونغ كونغ؛ مع استبعاد أيام الأحد العادية
`HRV`	متاح	متاح	الإجازات الرسمية الوطنية وأيام عدم العمل؛ مع استبعاد المناسبات التذكارية والأيام الخاصة بالطوائف
`IDN`	متاح	متاح	العطلات الوطنية والإجازة الجماعية، مع تصنيف منفصل
`IND`	غير متاح بعد	غير متاح بعد	مراجعة المصدر جارية
`IRL`	متاح	متاح	الإجازات الرسمية الوطنية؛ مع استبعاد البدائل الخاصة بأصحاب العمل واستحقاقات الإجازات
`ITA`	متاح	متاح	الإجازات الرسمية المدنية على المستوى الوطني؛ مع استبعاد الإغلاقات الإقليمية وإغلاقات أصحاب العمل
`JPN`	متاح	متاح	الإجازات الرسمية الوطنية
`KOR`	غير متاح بعد	غير متاح بعد	مراجعة المصدر جارية
`LTU`	متاح	متاح	الإجازات الرسمية الوطنية بموجب المادة 123 من قانون العمل؛ وتُستبعد الفعاليات الإقليمية
`LUX`	متاح	متاح	الإجازات الرسمية الوطنية
`LVA`	متاح	متاح	الإجازات الرسمية الوطنية؛ مع استبعاد المناسبات التذكارية والفعاليات الإقليمية
`MEX`	متاح	متاح	تواريخ الراحة الوطنية الإلزامية من العمل؛ مع استبعاد إغلاقات البنوك والإغلاقات الخاصة بالولايات أو البلديات وحدها والإغلاقات القطاعية
`NLD`	متاح	متاح	الإجازات الرسمية الوطنية؛ الإجازة حسب شروط العمل
`NOR`	متاح	غير متاح بعد	أيام إغلاق نظام التسوية لدى Norges Bank؛ ليست تقويمًا عامًا لعطلات العمل
`NZL`	متاح	متاح	العطلات الوطنية والتواريخ المعتمدة للاحتفال بها؛ مع استبعاد الذكريات السنوية الإقليمية
`PHL`	غير متاح بعد	غير متاح بعد	مراجعة المصدر جارية
`POL`	متاح	متاح	الإجازات الرسمية الوطنية؛ مع استبعاد أيام الأحد العادية والفعاليات الإقليمية وإغلاقات أصحاب العمل
`PRT`	متاح	متاح	الإجازات الرسمية الوطنية الإلزامية؛ مع استبعاد العطلات الاختيارية والبلدية والإقليمية
`RUS`	غير متاح بعد	غير متاح بعد	مراجعة المصدر جارية
`SAU`	غير متاح بعد	غير متاح بعد	مراجعة المصدر جارية
`SGP`	متاح	متاح	الإجازات الرسمية الوطنية والتواريخ المعتمدة للاحتفال بها التي يحددها المصدر
`SVK`	متاح	متاح	الإجازات الرسمية الوطنية
`SVN`	متاح	متاح	الإجازات الرسمية الوطنية وأيام عدم العمل؛ مع استبعاد المناسبات التذكارية التي لا تُعد أيام عدم عمل والعطلات المحلية
`SWE`	متاح	متاح	الإجازات الرسمية الوطنية
`TUR`	غير متاح بعد	غير متاح بعد	مراجعة المصدر جارية
`TWN`	متاح	متاح	تقويم الدوائر الحكومية؛ مع استبعاد إغلاقات القطاع الخاص والأسواق
`USA`	متاح	متاح	عطلات الموظفين الاتحاديين والتواريخ المعتمدة للاحتفال بها؛ مع استبعاد عطلات الولايات
`ZAF`	متاح	متاح	الإجازات الرسمية الوطنية؛ تُستبعد العطلات الخاصة بالمدارس فقط

تصف الإدخالات المتاحة النطاق المذكور فقط، لا كل عطلة محلية أو قطاعية. يسمح التحقق بالسنوات 1900–2200، دون أن يعني ذلك توفر بيانات تاريخية.

تحتوي السنة المنشورة على 1–400 حدث. ويعيد تقويم البلد والسنة غير المنشور 404 calendar_not_published؛ أما التقويم الذي يتعذر تقديمه بأمان حاليًا فيعيد 503 calendar_coverage_unavailable. لا يمكن لعملية بحث ناجحة عن تاريخ أن تعيد مصفوفة فارغة إلا إذا كانت بيانات سنته منشورة. ولا تثبت الإجازات الرسمية إغلاق البنوك أو البورصات.

يُرجع 403 plan_upgrade_required عندما تكون السنة أو التاريخ أو النطاق قبل نافذة السجل في خطتك (Free لمدة 12 شهرًا، وBasic لمدة 5 سنوات، وPro للسجل الكامل).

يستهلك كل استدعاء ناجح طلبًا واحدًا من الحصة الشهرية المشتركة، بما في ذلك نتائج البحث الفارغة عن التواريخ. لا تستهلك الأخطاء الحصة الشهرية؛ لكن تحديد معدل الطلبات خلال الفترة الزمنية القصيرة يظل ساريًا. اقرأ المواصفات المشتركة للأخطاء والحصة.