Iranian holidays with iranian_holidays

Iran's official holidays for jalali_date dates in Dart: calculated offline including the lunar Hijri ones, or from holidayapi.ir, Calendarific or Google Calendar.

Iranian holidays and events for jalali_date dates. تعطیلات و مناسبت‌های تقویم رسمی ایران برای تاریخ‌های jalali_date.

Two ways to get holidays, and you choose one explicitly:

• Offline: OfflineHolidaySource calculates the official holidays on the device, with no network and no third party. Religious holidays follow the lunar Hijri calendar; their dates come from the predicted first sighting of the new crescent in Iran.
• Online: a holiday service such as holidayapi.ir, Calendarific, or Google Calendar, or one of your own. It follows announcements and lists every event of the calendar, not only days off.

FallbackHolidaySource combines both: online first, offline when the request fails.

#Choosing a source

Not usable today: Nager.Date is free but has no Iranian data, and time.ir is a website without a public API.

Tell your users where holiday data comes from, for example on an about or settings screen; HolidaySource.name, website, and notice hold that text.

#Installation

dart pub add iranian_holidays

#Offline holidays

import 'package:jalali_date/jalali_date.dart';
import 'package:iranian_holidays/iranian_holidays.dart';

void main() {
  final offline = OfflineHolidaySource();

  final ashura = offline.dayOf(PersianDate(1405, 4, 4));
  print(ashura.isHoliday); // true
  print(ashura.holidays.first.description); // عاشورای حسینی
  print(ashura.holidays.first.additionalDescription); // 10 محرم 1448

  for (final day in offline.holidaysOf(1406)) {
    print('${day.date} ${day.holidays.map((e) => e.description).join(', ')}');
  }

  print(offline.hijriDate(PersianDate(1405, 1, 1))); // 1 شوال 1447
}

dayOf, holidaysOf, and hijriDate are synchronous; day and month implement HolidaySource like the online sources. holidaysOf lists the official holidays of a Jalali year without Fridays; dayOf and day count Fridays unless you pass fridaysAreHolidays: false.

#How Hijri holidays are calculated

A Hijri month starts the day after the evening its new crescent is first seen in Iran. The package computes the new moon and the positions of the Sun and the Moon at sunset (Meeus, Astronomical Algorithms), and checks Yallop's visibility criterion at eight cities across Iran, counting a crescent visible with optical aid (q >= -0.232). Months where the calendar published by the Iranian calendar authority differs are corrected from a table. Checked against the published calendar for every month with a holiday from 1387 to 1406, the result matches all of them. Without the table, the calculation alone matches 174 of these 186 months, and 109 of the 112 from 1395 on. The calendar itself lives in jalali_date as HijriDate and IranianHijri; use it directly when you need Hijri dates without holidays.

What the offline mode cannot do:

• A month officially starts when the crescent is actually seen, which is announced only days before. A later announcement that moves a holiday is not picked up. Pass the announced start yourself, or use an online source:

  dart

  final offline = OfflineHolidaySource(
    // 1 Muharram 1448 announced for 1405/03/27.
    hijriMonthStarts: {(1448, 1): PersianDate(1405, 3, 27)},
  );

• Changes to the holiday law are not picked up either; pass your own holidays list (built from OfficialHoliday.jalali and OfficialHoliday.hijri) if the law changes.

• It lists official days off only, not the many other events of the calendar.

#The official holidays

The Persian names are in OfficialHoliday.iran. Imam Reza is on 29 Safar even in years where Safar has 30 days, as on the published calendars. Fridays are holidays as well.

#Example: 1405 and 1406

Output of OfflineHolidaySource().holidaysOf(year), Fridays not listed. Both years match the calendar published on time.ir day for day. A Hijri holiday falls twice in one Jalali year when the lunar year (354 or 355 days) fits inside it: Eid al-Fitr in 1405.

#1405

#1406

#Online holidays

import 'package:jalali_date/jalali_date.dart';
import 'package:iranian_holidays/iranian_holidays.dart';

Future<void> main() async {
  final api = HolidayApiIrSource();
  print(api.notice); // read this before shipping

  final source = CachedHolidaySource(api);
  final day = await source.day(PersianDate(1403, 1, 1));
  print(day.isHoliday); // true
  print(day.holidays.first.description); // جشن نوروز/جشن سال نو

  final mehr = await source.month(1403, 7);
  print(mehr.where((d) => d.isHoliday).map((d) => d.date));
  api.close();
}

#Online first, offline as fallback

final source = FallbackHolidaySource(
  CachedHolidaySource(HolidayApiIrSource()),
  OfflineHolidaySource(),
);
final day = await source.day(PersianDate(1405, 4, 4)); // works without network

FallbackHolidaySource uses the second source only when the first throws HolidaySourceException.

#Caching

CachedHolidaySource keeps answers in memory, so each day is requested once; failed requests are retried on the next call. CalendarificSource and GoogleCalendarSource already cache whole years or months, so they do not need it. Errors from any source are HolidaySourceException, and API keys are replaced by REDACTED in its URL.

#Sources with your own API key

// Calendarific: https://calendarific.com, key from your account.
final calendarific = CalendarificSource(apiKey: calendarificKey);

// Google Calendar API: key from a Google Cloud project with the Calendar API.
final google = GoogleCalendarSource(apiKey: googleKey);

// Persian names from Google; tell it how days off are marked there.
final googleFa = GoogleCalendarSource(
  apiKey: googleKey,
  calendarId: GoogleCalendarSource.persianCalendarId,
  isHolidayEvent: (summary, description) => description.contains('تعطیل'),
);

// Keep the key on your server: a proxy that adds it and forwards the request.
final proxied = CalendarificSource(
  apiKey: 'unused',
  baseUri: Uri.parse('https://api.example.com/calendarific/'),
);

Read keys from your configuration (for example --dart-define), never from source code. These two classes are tested against the providers' documented response formats with mock clients; check the results against the official calendar before you rely on them.

#Writing your own source

class MyTableSource implements HolidaySource {
  @override
  String get name => 'Built-in table 1403';

  @override
  Uri get website => Uri.parse('https://example.com/holidays');

  @override
  String get notice => 'Official 1403 holidays, updated by hand.';

  static final _holidays = {
    PersianDate(1403, 1, 1): 'جشن نوروز',
    // ...
  };

  @override
  Future<HolidayDay> day(PersianDate date) async {
    final key = PersianDate(date.year, date.month, date.day);
    final name = _holidays[key];
    return HolidayDay(
      date: key,
      isHoliday: name != null || key.isWeekend,
      events: [if (name != null) HolidayEvent(description: name, isHoliday: true)],
    );
  }

  @override
  Future<List<HolidayDay>> month(int year, int month) {
    final first = PersianDate(year, month, 1);
    return Future.wait(first.daysUntil(first.lastDayOfMonth).map(day));
  }
}