해외 공휴일 여행: 공휴일과 히즈라력을 고려해 계획 세우기

여행 팀은 각 시장의 공휴일, 다음 공휴일, 히즈라력을 가져와 공휴일을 고려한 계획을 세울 수 있습니다. 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 날도 함께 공표하기 때문입니다.

한 해를 나열하고 연휴 찾기

공휴일이 주말과 이어지면 여행 수요가 늘어납니다. 연도 엔드포인트는 한 나라의 모든 공휴일을 돌려주고, 짧은 스크립트가 이를 주말과 합쳐 4일 이상 이어지는 휴일 구간을 찾을 수 있습니다. 이 스크립트는 scope 필터 없이 인도네시아의 2026년을 읽으므로 단체 휴가일도 쉬는 날로 셉니다.

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)일을 collective_leave scope로 올려 둡니다. 이런 날은 공휴일 바로 옆에 붙어 휴일을 늘립니다. 그래서 위 표에서 2026년 3월 21일의 Eid al-Fitr가 7일 연휴 구간에 들어 있습니다.

그 날들을 빼려면 scope=national_public을 추가하세요. 위 스크립트처럼 휴일 전체를 보고 싶다면 필터를 빼세요.

에 게시되었습니다.

다음 단계