جدولة الاجتماعات حسب العطل والإصدارات في عدة دول

معرفة موعد الإغلاق القادم لدولة ما

يعيد GET /v1/calendars/holidays/{country}/next أول عطلة في from_date أو بعده. يسأل هذا الطلب عن اليابان اعتبارًا من 9 نوفمبر 2026.

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

{
  "country": "JPN",
  "coverage": [
    {
      "scope": "national_public",
      "subdivision_codes": []
    }
  ],
  "holiday": {
    "date": "2026-11-23",
    "name": "Labor Thanksgiving Day",
    "holiday_key": "labor_thanksgiving_day",
    "local_name": "勤労感謝の日",
    "scope": "national_public",
    "subdivision_codes": []
  }
}

العطلة هي يوم الشكر للعمل في 23 نوفمبر، وscope هو national_public. يحمل local_name الاسم الياباني، وholiday_key هو المفتاح الثابت لهذا النوع من الأيام. وبالنسبة لدولة واحدة، يجيب هذا الاستدعاء عن سؤال التخطيط. وبالنسبة لعدة دول، اسأل كل واحدة واحتفظ بأبكر إجابة، أو اقرأ السنة كاملة كما في القسم التالي.

إيجاد الأيام الخالية في كل الدول بمرور واحد

1. احصل على مفتاح API احصل على مفتاح API من صفحة التسجيل واحفظه في NARWHAL_API_KEY.
2. تحديد الدول والنافذة الزمنية يستخدم السكربت USA وDEU وJPN وIDN، من 9 إلى 30 نوفمبر، ويبحث عن 3 أيام عمل متتالية خالية. ثلاثة أيام مجرد مثال، فاستخدم الطول الذي تحتاجه نافذة الإصدار أو الصيانة. غيّر قائمة الدول والتواريخ لتناسب فرقك.
3. جمع تواريخ الإغلاق يعيد طلب واحد لكل دولة عطل السنة. يخزّن السكربت كل date في خريطة من التاريخ إلى مجموعة الدول المغلقة. والتاريخ المشترك بين دولتين يحمل الرمزين معًا.
4. المرور على أيام الأسبوع وكتابة التقرير يسرد السكربت أيام الأسبوع التي تُغلق فيها دولة واحدة على الأقل، ثم يجد أول سلسلة متتالية من أيام العمل الخالية.
   Python، أيام الإغلاق وأول سلسلة خالية

   import os
   from collections import defaultdict
   from datetime import date, timedelta
   import requests
   
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   COUNTRIES = ["USA", "DEU", "JPN", "IDN"]
   START, END, NEED = date(2026, 11, 9), date(2026, 11, 30), 3
   
   closed = defaultdict(set)  # date -> countries closed that day
   for country in COUNTRIES:
       r = requests.get(
           f"https://api.narwhalapi.com/v1/calendars/holidays/{country}/{START.year}",
           headers=HEADERS,
           timeout=10,
       )
       r.raise_for_status()
       for h in r.json()["holidays"]:
           closed[h["date"]].add(country)
   
   days, day = [], START
   while day <= END:
       if day.weekday() < 5:
           days.append((day, sorted(closed.get(day.isoformat(), []))))
       day += timedelta(1)
   
   for day, who in days:
       if who:
           print(day.strftime("%a %d %b"), "closed:", ", ".join(who))
   
   for i in range(len(days) - NEED + 1):
       if all(not who for _, who in days[i:i + NEED]):
           print(f"first {NEED} clear business days in a row start:", days[i][0].strftime("%a %d %b"))
           break

Wed 11 Nov closed: USA
Mon 23 Nov closed: JPN
Thu 26 Nov closed: USA
first 3 clear business days in a row start: Thu 12 Nov

من بين أيام الأسبوع الـ 16 بين 9 و30 نوفمبر، فيها 3 أيام إغلاق و13 يومًا خالية في الدول الأربع كلها. وتبدأ أول سلسلة من 3 أيام عمل خالية يوم الخميس 12 نوفمبر. لا يستخدم السكربت أي مرشح scope، لذا تُحتسب أيام الإجازة الجماعية في إندونيسيا مغلقة. أضف scope=national_public إلى طلب تلك الدولة لاستبعادها.

أيام الإغلاق التي يجب إبعادها عن الخطة

إصدار مجدول يوم الأربعاء 11 نوفمبر سيصطدم بمكتب أمريكي مغلق. وعيدا الشكر عطلتان مختلفتان في دولتين مختلفتين، بقيمتي holiday_key هما labor_thanksgiving_day وthanksgiving_day، وتُغلق كل منهما بلدها فقط. والمطابقة بالمفتاح لا بالاسم تبقيهما منفصلتين.

لعرض أيام الإغلاق أمام من يجدولون العمل، أنشئ خلاصة تقويم بالقيمة true في include_holidays والقيمة false في include_releases عبر POST /v1/calendars/subscriptions. يصف وثائق اشتراكات التقويم الطلب. لا تشغّل هذه الصفحة الاستدعاء لأنه ينشئ خلاصة.

ما الذي يغطيه كل scope في هذه المقارنة

اقرأ coverage في كل استجابة قبل أن تعتمد على القائمة. فهو يسمّي النطاقات والتقسيمات التي يغطيها التقويم، وتختلف النطاقات من دولة إلى أخرى. وتحتاج الدولة التي تحمل إدخالاتها رموز تقسيمات فرعية، مثل المملكة المتحدة، إلى فحص إضافي: احتفظ بالإدخال حين تكون قائمته فارغة أو تتضمن منطقة المكتب.

هل تهم عطل نهاية الأسبوع في الجدولة؟

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

ماذا لو كان فريقي في دولة بها عطل إقليمية؟

ليس لنقطة السنة معامل للمنطقة، لذا صفِّ بـ subdivision_codes في كودك. القائمة الفارغة تعني أن العطلة وطنية. وفي المملكة المتحدة تظهر كل عطلة مصرفية مرة لكل مجموعة من الأمم، فقد يكون للتاريخ الواحد عدة إدخالات.

كم طلبًا تحتاج نافذة تمتد عبر عدة سنوات؟

طلب واحد لكل دولة وسنة. وتحتاج النافذة التي تتجاوز 31 ديسمبر إلى قائمة السنة التالية لكل دولة أيضًا، والسنة التي لم يُنشر لها تقويم تعيد 404 بالرمز calendar_not_published. استعد لهذه الاستجابة في الجداول البعيدة المدى، واحتفظ بقائمة كل سنة في ذاكرة مؤقتة حتى لا تعيد التشغيلات المتكررة الطلب.