圍繞國定假日和伊斯蘭曆（回曆）規劃旅遊

旅遊團隊可以透過取得各市場的國定假日、下一個假日和回曆，圍繞假期做規劃。Narwhal 依國家和年份提供這些日期，一個簡短的腳本就能把它們整理成連假。

查找某個市場的下一個國定假日

訂位團隊會圍繞某個市場休市或擁擠的日子來做安排。Narwhal API 沒有需求、預訂或價格資料，它提供的是日期。先從 next 端點開始，它回傳某個日期當天或之後的第一個假日。下面的請求查詢 2026 年 11 月 3 日之後的印尼，並只保留 national_public 這個 scope。

curl，印尼的下一個國定假日
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。去掉 scope 過濾後，同樣的請求會改為回傳 2026 年 12 月 24 日的聖誕集體休假，因為印尼還會公布 collective_leave 的日子。

列出一整年並找出連假

當國定假日與週末相連時，旅遊需求就會上升。年度端點回傳一個國家的所有假日，一個簡短的腳本可以把它們與週末合併，找出連續四天或更長的休息日。這個腳本讀取印尼 2026 年的資料，不使用 scope 過濾，因此集體休假日也算作休息日。

python，圍繞國定假日的連續休息日
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 年輸出四段連續休息日。

從到天數該段休息日內的假日
2026-02-142026-02-174農曆新年集體休假、農曆新年
2026-03-182026-03-247Nyepi 集體休假、Nyepi、Eid al-Fitr 集體休假、Eid al-Fitr
2026-05-142026-05-174耶穌升天節、耶穌升天節集體休假
2026-12-242026-12-274聖誕節集體休假、聖誕節

改一下國家代碼和年份，就可以對另一個市場做同樣的檢查。這個腳本把週六和週日當作週末，如果某個國家的工作週不同，請修改這條規則。要涵蓋多個市場的團隊，對每個國家和年份各呼叫一次年度端點，並把各國的休息日區段儲存在同一張表裡。

為穆斯林人口占多數的市場對齊回曆

這些市場的許多假日遵循回曆，所以它們的西曆日期每年都在變。Hijri 端點接受一個回曆年（AH），回傳該年十二個月及每月的第一天。涵蓋印尼、沙烏地阿拉伯、馬來西亞、土耳其、埃及和巴基斯坦。AH 1447 包含 2026 年的齋月，下面的請求只保留其中的第九個月和第十個月。

curl，印尼的回曆月份
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。在這份回應中，齋月按推算從 2026 年 2 月 18 日開始，按印尼的曆表則從 2026 年 2 月 19 日開始。第十個月從 2026 年 3 月 21 日開始，這正是印尼假日清單中 Eid al-Fitr 的日期。status 說明這個日期的確定程度。

一個西曆年會跨越兩個回曆年。印尼的曆表把 AH 1448 定在 2026 年 6 月 16 日開始，所以要規劃整個 2026 年，需要 1447 和 1448 兩份回應。

回曆日期的確定程度如何？

請看 status。calculated 表示 API 只有推算出的日期，official_start 為 null；published 表示存在官方年度曆表，但這樣的曆表仍可能變動；announced 則是經過觀月或 isbat 會議之後的最終決定。

對於 AH 1447，沙烏地阿拉伯的回應在第九和第十個月回傳 calculated，而印尼和馬來西亞回傳 published。把狀態為 calculated 或 published 的 Eid 當作規劃用的日期，臨近出行時再核對一次。

API 有學校假期嗎？

沒有。API 沒有學校日曆。它的假日 scope 包括 national_public、regional_public、bank、federal_government、central_government、collective_leave、public_sector 和 private_sector，沒有一個是學期。把國定假日和連假日期當作日曆訊號，學校日期請從你自己的來源取得。

如何把屬於同一個假日的列歸併在一起？

使用 holiday_key。在印尼 2026 年的回應中，農曆新年在 2 月 16 日以集體休假出現，在 2 月 17 日以全國國定假日出現，兩列都帶有鍵 lunar_new_year。依這個鍵分組，就能把一個假日只算一次，再看每一列的 scope，區分哪些天是節日本身，哪些是前後增加的休息日。

集體休假對出行意味著什麼？

印尼在全國國定假日之外，還列出集體休假日（cuti bersama），其 scope 為 collective_leave。它們緊挨著假日，會延長假期。這就是為什麼在上面的表中，2026 年 3 月 21 日的 Eid al-Fitr 處在一段七天的休息日裡。

加上 scope=national_public 即可排除這些日子。如果想看完整的假期，就像上面的腳本那樣不加過濾。

發布於 。

後續步驟