تخطيط السفر حسب العطل الرسمية والتقويم الهجري

العثور على العطلة الرسمية التالية في سوق

يخطط فريق الحجز حول الأيام التي يُغلق فيها السوق أو يزدحم. لا تحتوي Narwhal API على بيانات طلب أو حجز أو أسعار، وما توفره هو التواريخ. ابدأ بنقطة نهاية next التي تعيد أول عطلة في تاريخ ما أو بعده. يسأل هذا الطلب عن إندونيسيا بعد 3 نوفمبر 2026 ويُبقي على نطاق national_public فقط.

curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/calendars/holidays/IDN/next?from_date=2026-11-03&scope=national_public"

{
  "country": "IDN",
  "coverage": [
    {
      "scope": "national_public",
      "subdivision_codes": []
    }
  ],
  "holiday": {
    "date": "2026-12-25",
    "name": "Christmas Day",
    "holiday_key": "christmas_day",
    "local_name": "Kelahiran Yesus Kristus",
    "scope": "national_public",
    "subdivision_codes": []
  }
}

يحتوي كائن holiday على date وname بالإنجليزية وlocal_name وscope. وتبيّن قائمة coverage النطاقات التي أبقى عليها المرشِّح. وإذا أسقطت مرشِّح scope أعاد الطلب نفسه إجازة عيد الميلاد الجماعية في 24 ديسمبر 2026 بدلًا من ذلك، لأن إندونيسيا تنشر أيام collective_leave أيضًا.

سرد سنة كاملة وإيجاد العطلات الممتدة

يرتفع الطلب على السفر عندما تتصل العطلة بنهاية الأسبوع. تعيد نقطة نهاية السنة كل عطل البلد، ويمكن لسكربت قصير ضمّها إلى عطلات نهاية الأسبوع لإيجاد فترات إجازة من أربعة أيام أو أكثر. يقرأ هذا السكربت إندونيسيا لعام 2026 دون مرشِّح نطاق، فتُحسب أيام الإجازة الجماعية أيام راحة.

import json
import os
import urllib.request
from datetime import date, timedelta

def get(path):
    req = urllib.request.Request(
        "https://api.narwhalapi.com" + path,
        headers={"Authorization": "Bearer " + os.environ["NARWHAL_API_KEY"]},
    )
    with urllib.request.urlopen(req, timeout=30) as r:
        return json.load(r)

def long_breaks(country, year, min_days=4):
    names = {}
    for h in get(f"/v1/calendars/holidays/{country}/{year}")["holidays"]:
        names.setdefault(date.fromisoformat(h["date"]), []).append(h["name"])
    day, end, runs = date(year, 1, 1), date(year, 12, 31), []
    while day <= end:
        if day.weekday() >= 5 or day in names:
            start = day
            while day <= end and (day.weekday() >= 5 or day in names):
                day += timedelta(days=1)
            if (day - start).days >= min_days and any(d in names for d in
                    (start + timedelta(n) for n in range((day - start).days))):
                runs.append((start, day - timedelta(days=1)))
        else:
            day += timedelta(days=1)
    return runs, names

runs, names = long_breaks("IDN", 2026)
for first, last in runs:
    days = [first + timedelta(n) for n in range((last - first).days + 1)]
    print(first, last, len(days), "days:", "; ".join(dict.fromkeys(n for d in days for n in names.get(d, []))))

يطبع السكربت أربع فترات لإندونيسيا في عام 2026.

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

مواءمة التقويم الهجري للأسواق ذات الأغلبية المسلمة

تتبع عدة عطل في هذه الأسواق التقويم الهجري، فتتحرك تواريخها الميلادية كل عام. تأخذ نقطة نهاية Hijri سنة هجرية (AH) وتعيد أشهرها الاثني عشر مع أول يوم في كل شهر. وتغطي إندونيسيا والسعودية وماليزيا وتركيا ومصر وباكستان. تحتوي السنة AH 1447 على رمضان 2026، ويُبقي هذا الطلب على شهريها التاسع والعاشر.

curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/calendars/hijri/IDN/1447"

{
  "country": "IDN",
  "year": 1447,
  "months": [
    {
      "month": 9,
      "calculated_start": "2026-02-18",
      "official_start": "2026-02-19",
      "status": "published",
      "source": "kemenag_table",
      "source_url": "https://aceh.kemenag.go.id/storage/berita_informasi/01K7GE96M0ZVRJ62Z520RMYG1B.pdf",
      "authority": "Kementerian Agama (Kemenag), Sidang Isbat for Ramadan, Shawwal and Dhu al-Hijjah",
      "announced_on": null,
      "decision_expected_on": "2026-02-17",
      "revised": false,
      "updated_at": "2026-11-02T16:31:12.025432Z"
    },
    {
      "month": 10,
      "calculated_start": "2026-03-20",
      "official_start": "2026-03-21",
      "status": "published",
      "source": "kemenag_table",
      "source_url": "https://aceh.kemenag.go.id/storage/berita_informasi/01K7GE96M0ZVRJ62Z520RMYG1B.pdf",
      "authority": "Kementerian Agama (Kemenag), Sidang Isbat for Ramadan, Shawwal and Dhu al-Hijjah",
      "announced_on": null,
      "decision_expected_on": "2026-03-18",
      "revised": false,
      "updated_at": "2026-11-02T16:31:12.279058Z"
    }
  ]
}

calculated_start هو اليوم الأول بالحساب الفلكي. وofficial_start هو اليوم الذي حددته سلطة البلد، وقيمته null إلى أن يوجد. في هذه الاستجابة يبدأ رمضان في 18 فبراير 2026 بالحساب، وفي 19 فبراير 2026 بالجدول الإندونيسي. ويبدأ الشهر العاشر في 21 مارس 2026، وهو تاريخ Eid al-Fitr في قائمة العطل الإندونيسية. وتبيّن status مدى نهائية التاريخ.

تمتد السنة الميلادية على سنتين هجريتين. يبدأ جدول إندونيسيا السنة AH 1448 في 16 يونيو 2026، لذا يحتاج تخطيط عام 2026 كله إلى استجابتي 1447 و1448.

ما مدى نهائية التاريخ الهجري؟

اقرأ status. تعني القيمة calculated أن الـ API لا تملك سوى اليوم المحسوب وأن official_start تساوي null. وتعني published وجود جدول سنوي رسمي، ويمكن أن يتغير هذا الجدول أيضًا. أما announced فهي القرار النهائي بعد رؤية الهلال أو اجتماع الإثبات (isbat).

في السنة AH 1447 تعيد استجابة السعودية القيمة calculated للشهرين التاسع والعاشر، بينما تعيد إندونيسيا وماليزيا published. اعتبر العيد ذا الحالة calculated أو published تاريخًا للتخطيط وتحقق منه مرة أخرى قرب موعد السفر.

هل في الـ API عطل مدرسية؟

لا. ليس في الـ API تقويم مدرسي. نطاقات العطل فيها هي national_public وregional_public وbank وfederal_government وcentral_government وcollective_leave وpublic_sector وprivate_sector، ولا يمثل أي منها فصلًا دراسيًا. استخدم تواريخ العطل الرسمية والعطلات الممتدة إشارةً تقويمية، وأحضر التواريخ المدرسية من مصدرك الخاص.

كيف أجمّع الصفوف التي تنتمي إلى عطلة واحدة؟

استخدم holiday_key. ففي استجابة إندونيسيا لعام 2026 يظهر رأس السنة الصينية في 16 فبراير إجازةً جماعية وفي 17 فبراير عطلة رسمية وطنية، ويحمل الصفان المفتاح lunar_new_year. جمّع بهذا المفتاح لتحسب العطلة مرة واحدة، واقرأ scope في كل صف لتعرف أي الأيام هو العطلة نفسها وأيها أيام إضافية حولها.

ماذا تعني الإجازة الجماعية للرحلة؟

تسرد إندونيسيا أيام الإجازة الجماعية (cuti bersama) بجانب عطلها الرسمية الوطنية بنطاق collective_leave. وتقع بجوار العطلة فتمدد الراحة. ولهذا يقع Eid al-Fitr في 21 مارس 2026 ضمن فترة إجازة من سبعة أيام في الجدول أعلاه.

أضف scope=national_public لاستبعاد تلك الأيام. واترك المرشِّح إن أردت العطلة بكاملها، كما يفعل السكربت أعلاه.