مرجع واجهة API للتقاويم
العطلات الرسمية السنوية وعمليات البحث عن التواريخ والعطلة التالية عبر REST وMCP.
الإصدار التجريبي العام المباشر
استخدم مفتاح 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 الاستمارة. معلمتا الدولة والتاريخ/السنة مطلوبتان. يختار مرشح نطاق اختياري فئة العطلة. لا يوجد ترقيم صفحات أو مرشح تقسيم فرعي.
كائن العطلة المشترك
| حقل | النوع | المعنى |
|---|---|---|
date | التاريخ سلسلة نصية | تاريخ التقويم المحلي، وليس طابعًا زمنيًا للاستيعاب. |
name | سلسلة نصية | الاسم الإنجليزي/المعروض، من 1 إلى 256 حرفًا. |
local_name | سلسلة نصية أو قيمة فارغة | الاسم المحلي عند توفره، من 1 إلى 256 حرفًا. |
subdivision_codes | سلسلة نصية مصفوفة | رموز مرتبة وفريدة مثل GB-SCT، تابعة للدولة. |
nationwide | منطقي | تتطلب القيمة الصحيحة قائمة تقسيمات فرعية فارغة؛ وتتطلب القيمة الخاطئة قائمة غير فارغة. |
scope | سلسلة نصية | فئة العطلة، مثل national_public أو bank أو federal_government أو collective_leave. |
observed | قيمة منطقية أو قيمة فارغة | حالة الرصد أو الاستبدال صريحة. وتعني القيمة الفارغة أن الحالة غير معروفة، لا أنها خاطئة. |
تتضمن كائنات العطلات العادية الحقول السبعة كلها. وتتضمن كل استجابة أيضًا إقرارات التغطية مع النطاق وnationwide وsubdivision_codes، حتى عند نتيجة تواريخ فارغة. وتبقى معرّفات الطلبات والحصة في الترويسات. ولا تُدرج عناوين المصادر وأوقات فحص الإدخال في أجسام الاستجابات الناجحة.
التغطية والحدود
| الدولة | 2026 | 2027 | النطاق المنشور |
|---|---|---|---|
ARG | غير متاح بعد | غير متاح بعد | مراجعة المصدر جارية |
AUS | متاح | متاح | نيو ساوث ويلز فقط: العطلات الرسمية والمصرفية الإقليمية |
BRA | غير متاح بعد | غير متاح بعد | مراجعة المصدر جارية |
CAN | غير متاح بعد | غير متاح بعد | مراجعة المصدر جارية |
CHN | متاح | غير متاح بعد | فترات العطلات الوطنية؛ تُستبعد أيام العمل التعويضية |
FRA | متاح | متاح | العطلات النظامية الوطنية العامة؛ مع استبعاد الإضافات الإقليمية |
DEU | غير متاح بعد | غير متاح بعد | مراجعة المصدر جارية |
IND | غير متاح بعد | غير متاح بعد | مراجعة المصدر جارية |
IDN | متاح | غير متاح بعد | العطلات الوطنية والإجازة الجماعية، مع تصنيف منفصل |
ITA | غير متاح بعد | غير متاح بعد | مراجعة المصدر جارية |
JPN | متاح | متاح | العطلات الرسمية الوطنية |
MEX | غير متاح بعد | غير متاح بعد | مراجعة المصدر جارية |
KOR | غير متاح بعد | غير متاح بعد | مراجعة المصدر جارية |
RUS | غير متاح بعد | غير متاح بعد | مراجعة المصدر جارية |
SAU | غير متاح بعد | غير متاح بعد | مراجعة المصدر جارية |
ZAF | غير متاح بعد | متاح | العطلات الرسمية الوطنية؛ تُستبعد العطلات الخاصة بالمدارس فقط |
TUR | غير متاح بعد | غير متاح بعد | مراجعة المصدر جارية |
GBR | متاح | متاح | عطلات البنوك في إنجلترا وويلز واسكتلندا وأيرلندا الشمالية |
USA | متاح | متاح | عطلات الموظفين الاتحاديين والتواريخ المرصودة؛ مع استبعاد عطلات الولايات |
ما زال الهدف تسع عشرة دولة. تصف الإدخالات المتاحة النطاق المذكور فقط، لا كل عطلة محلية أو قطاعية. يسمح التحقق من السنة بـ1900–2200؛ وهذا ليس ادعاءً بالتغطية التاريخية.
تحتوي السنة المنشورة على 1–400 حدث. وتعيد التغطية المفقودة أو المسحوبة 503 calendar_coverage_unavailableلا يمكن لبحث تاريخ ناجح أن يعيد مصفوفة فارغة إلا عندما تكون سنته منشورة. ولا تثبت العطلات الرسمية إغلاق بنك أو بورصة.
تستهلك الاستدعاءات الناجحة طلباً شهرياً مشتركاً واحداً، بما في ذلك نتائج التواريخ الفارغة. لا تستهلك الأخطاء الحصة الشهرية؛ لكن تحديد المعدل قصير النافذة لا يزال سارياً. اقرأ عقد الأخطاء والحصة المشترك.