Using the Zmanim API 1.3.0 Jewish Calendar Code

Sunrise CalendarThe recently released Zmanim API 1.3.0 added Jewish calendar support to the API. Previously, the API had zmanim support, but no Jewish calendar support. While the calendar code is in beta mode and is subject to API changes, below are some simple code examples using the current 1.3.0 release. These examples of the use of the JewishCalendar and HebrewDateFormatter classes do not fully cover the functionality available in the Zmanim API. Please read the JavaDocs and experiment. Please let me know if there are any calendar related items that you feel should change or be added to the API.

Setting and outputting formatted dates

JewishCalendar jd = new JewishCalendar(); // current date 23 Nissan, 5773
HebrewDateFormatter hdf = new HebrewDateFormatter();
System.out.println(jd); // prints hebrew date in English chars - 23 Nissan, 5773
hdf.setHebrewFormat(true); // change formatting to Hebrew
System.out.println(hdf.format(jd)); // date formatted in Hebrew
jd.setJewishDate(5729, JewishDate.SHEVAT, 21); // set the date to 21 Shevat, 5729
System.out.println(hdf.format(jd)); // date formatted in Hebrew
jd.setJewishDate(5772, JewishDate.NISSAN, 18); // set date to third day of Pesach
System.out.println(hdf.format(jd));
System.out.println(hdf.formatYomTov(jd)); //output Chol Hamoed Pesach in Hebrew
hdf.setHebrewFormat(false); // change formatting to default
System.out.println(hdf.format(jd)); // prints Hebrew date in English chars - 18 Nissan, 5772
System.out.println(hdf.formatYomTov(jd)); //output Chol Hamoed Pesach

Output:

23 Nissan, 5773
כ״ג ניסן תשע״ג
כ״א שבט תשכ״ט
י״ח ניסן תשע״ב
חול המועד פסח
18 Nissan, 5772
Chol Hamoed Pesach

Parshas Hashavua

Please note that the parsha will only input if the date is a Shabbos. This is something that may change down the line.

HebrewDateFormatter hdf = new HebrewDateFormatter();
JewishCalendar jd = new JewishCalendar(5773, JewishDate.NISSAN, 12);
System.out.println(hdf.formatParsha(jd));
hdf.setHebrewFormat(true);
System.out.println(hdf.formatParsha(jd));
jd.back();
System.out.println("Parsha on Friday [" + hdf.formatParsha(jd) + "]"); //no Parsha output on a non Shabbos
jd.setJewishDate(5773, JewishDate.TAMMUZ, 28); //double parsha
System.out.println(hdf.formatParsha(jd));

Output:

Tzav
צו
Parsha on Friday []
מטות מסעי

Rosh Chodesh

HebrewDateFormatter hdf = new HebrewDateFormatter();
JewishCalendar jd = new JewishCalendar(5773, JewishDate.NISSAN, 1);
if(jd.isRoshChodesh()){ //not necessary for formatter
	System.out.println(hdf.formatRoshChodesh(jd));
}
hdf.setHebrewFormat(true);
System.out.println(hdf.formatRoshChodesh(jd));
jd.forward();// roll calendar to second day of Nisan
System.out.println("output[" + hdf.formatRoshChodesh(jd) + "]"); //no output for Rosh Chodesh Formatting

Output:

Rosh Chodesh Nissan
ראש חודש ניסן
output[]

Daf Yomi

JewishCalendar jd = new JewishCalendar();
HebrewDateFormatter hdf = new HebrewDateFormatter();
System.out.println(hdf.format(jd)); //output current formatted date "13 Nissan, 5773"
Daf daf = jd.getDafYomiBavli(); //get the current daf
System.out.println(daf.getMasechtaTransliterated()); //outout transliterated masechta name "Eruvin"
System.out.println(daf.getDaf()); //output current daf (page) number "16"
System.out.println(hdf.formatDafYomiBavli(daf)); //outout the formatted date "Eruvin 16"
hdf.setHebrewFormat(true); //set formatted to Hebrew
System.out.println(hdf.format(jd)); //output date in Hebrew "י״ג ניסן תשע״ג"
System.out.println(daf.getMasechta()); // output masechta name in Hebrew "עירובין"
System.out.println(hdf.formatHebrewNumber(daf.getDaf()));//output the daf number formatted in Hebrew "ט״ז"
System.out.println(hdf.formatDafYomiBavli(daf)); //output daf and masechta in Hebrew "עירובין ט״ז"

Output:

13 Nissan, 5773
Eruvin
16
Eruvin 16
י״ג ניסן תשע״ג
עירובין
ט״ז
עירובין ט״ז

Chanukah

JewishCalendar jd = new JewishCalendar(5772, JewishDate.KISLEV, 25); //set date to first day of Chanukah
HebrewDateFormatter hdf = new HebrewDateFormatter();
System.out.println(jd);//output current transliterated date
System.out.println(jd.getDayOfChanukah()); //output #1
System.out.println(hdf.formatYomTov(jd)); //output Chanukah 1
hdf.setHebrewFormat(true); //set format to hebrew
System.out.println(hdf.formatHebrewNumber(jd.getDayOfChanukah())); //output 1 in Hebrew
System.out.println(hdf.formatYomTov(jd)); // output Chanukah 1 in hebrew

Output:

25 Kislev, 5772
1
Chanukah 1
א׳
א׳ חנוכה

Note, that there is no simple way at this point to output just Chanukah. This will likely change in the future to match Chanukah to the behavior of other Yomim Tovim.

Loop and output an entire year

JewishCalendar jc = new JewishCalendar(5773, JewishDate.TISHREI, 1);
jc.setInIsrael(false); //default false for clarity but not needed. Set to true for Israel
HebrewDateFormatter hdf = new HebrewDateFormatter();
hdf.setHebrewFormat(true);
HebrewDateFormatter hdfTransliterated = new HebrewDateFormatter();
String hebrewOutput = "";
String transliteratedOutput = "";
while(jc.getJewishYear() == 5773){
	hebrewOutput = hdf.format(jc);
	transliteratedOutput = hdfTransliterated.format(jc);
	if (jc.isYomTov() || jc.isTaanis()) {
		hebrewOutput += ", " + hdf.formatYomTov(jc);
		transliteratedOutput += ", " + hdfTransliterated.formatYomTov(jc);
	} else if(jc.getDayOfWeek() == 7){
		hebrewOutput += " - " + hdf.formatParsha(jc);
		transliteratedOutput += " - " + hdfTransliterated.formatParsha(jc);
	}
	if (jc.isChanukah()) {
		if (hebrewOutput.length() > 0) {
			hebrewOutput += ", ";
			transliteratedOutput += ", ";
		}
		hebrewOutput += hdf.formatYomTov(jc);
		transliteratedOutput  += hdfTransliterated.formatYomTov(jc);
	}
	if (jc.isRoshChodesh()) {
		if (hebrewOutput.length() > 0) {
			hebrewOutput += ", ";
			transliteratedOutput += ", ";
		}
		hebrewOutput += hdf.formatRoshChodesh(jc);
		transliteratedOutput += hdfTransliterated.formatRoshChodesh(jc);
	}
	if(jc.getDayOfOmer() > 0){
		hebrewOutput += ", ";
		transliteratedOutput += ", ";
		hebrewOutput += hdf.formatOmer(jc);
	}
	System.out.println(transliteratedOutput + " - " + hebrewOutput);
	jc.forward();
}

Output (most days removed for brevity):

1 Tishrei, 5773, Rosh Hashana - א׳ תשרי תשע״ג, ראש השנה
2 Tishrei, 5773, Rosh Hashana - ב׳ תשרי תשע״ג, ראש השנה
3 Tishrei, 5773, Fast of Gedalyah - ג׳ תשרי תשע״ג, צום גדליה
4 Tishrei, 5773 - ד׳ תשרי תשע״ג
...
6 Tishrei, 5773 - Vayeilech - ו׳ תשרי תשע״ג - וילך
...
10 Tishrei, 5773, Yom Kippur - י׳ תשרי תשע״ג, יום כיפור
...
15 Tishrei, 5773, Succos - ט״ו תשרי תשע״ג, סוכות
16 Tishrei, 5773, Succos - ט״ז תשרי תשע״ג, סוכות
17 Tishrei, 5773, Chol Hamoed Succos - י״ז תשרי תשע״ג, חול המועד סוכות
18 Tishrei, 5773, Chol Hamoed Succos - י״ח תשרי תשע״ג, חול המועד סוכות
19 Tishrei, 5773, Chol Hamoed Succos - י״ט תשרי תשע״ג, חול המועד סוכות
20 Tishrei, 5773, Chol Hamoed Succos - כ׳ תשרי תשע״ג, חול המועד סוכות
21 Tishrei, 5773, Hoshana Rabbah - כ״א תשרי תשע״ג, הושענא רבה
22 Tishrei, 5773, Shemini Atzeres - כ״ב תשרי תשע״ג, שמיני עצרת
23 Tishrei, 5773, Simchas Torah - כ״ג תשרי תשע״ג, שמחת תורה
...
30 Tishrei, 5773, Rosh Chodesh Cheshvan - ל׳ תשרי תשע״ג, ראש חודש חשוון
1 Cheshvan, 5773, Rosh Chodesh Cheshvan - א׳ חשוון תשע״ג, ראש חודש חשוון
...
25 Kislev, 5773, Chanukah 1 - כ״ה כסלו תשע״ג, א׳ חנוכה
26 Kislev, 5773, Chanukah 2 - כ״ו כסלו תשע״ג, ב׳ חנוכה
27 Kislev, 5773, Chanukah 3 - כ״ז כסלו תשע״ג, ג׳ חנוכה
28 Kislev, 5773, Chanukah 4 - כ״ח כסלו תשע״ג, ד׳ חנוכה
29 Kislev, 5773, Chanukah 5 - כ״ט כסלו תשע״ג, ה׳ חנוכה
1 Teves, 5773, Chanukah 6, Rosh Chodesh Teves - א׳ טבת תשע״ג, ו׳ חנוכה, ראש חודש טבת
2 Teves, 5773 - Miketz, Chanukah 7 - ב׳ טבת תשע״ג - מקץ, ז׳ חנוכה
3 Teves, 5773, Chanukah 8 - ג׳ טבת תשע״ג, ח׳ חנוכה
...
10 Teves, 5773, Tenth of Teves - י׳ טבת תשע״ג, עשרה בטבת
...
15 Shevat, 5773, Tu B'Shvat - ט״ו שבט תשע״ג, ט״ו בשבט
...
21 Shevat, 5773 - כ״א שבט תשע״ג
...
11 Adar, 5773, Fast of Esther - י״א אדר תשע״ג, תענית אסתר
...
14 Adar, 5773, Purim - י״ד אדר תשע״ג, פורים
15 Adar, 5773, Shushan Purim - ט״ו אדר תשע״ג, פורים שושן
...
27 Adar, 5773 - Vayakhel Pekudei - כ״ז אדר תשע״ג - ויקהל פקודי
...
15 Nissan, 5773, Pesach - ט״ו ניסן תשע״ג, פסח
16 Nissan, 5773, Pesach,  - ט״ז ניסן תשע״ג, פסח, א׳ בעומר
17 Nissan, 5773, Chol Hamoed Pesach,  - י״ז ניסן תשע״ג, חול המועד פסח, ב׳ בעומר
18 Nissan, 5773, Chol Hamoed Pesach,  - י״ח ניסן תשע״ג, חול המועד פסח, ג׳ בעומר
19 Nissan, 5773, Chol Hamoed Pesach,  - י״ט ניסן תשע״ג, חול המועד פסח, ד׳ בעומר
20 Nissan, 5773, Chol Hamoed Pesach,  - כ׳ ניסן תשע״ג, חול המועד פסח, ה׳ בעומר
21 Nissan, 5773, Pesach,  - כ״א ניסן תשע״ג, פסח, ו׳ בעומר
22 Nissan, 5773, Pesach,  - כ״ב ניסן תשע״ג, פסח, ז׳ בעומר
23 Nissan, 5773,  - כ״ג ניסן תשע״ג, ח׳ בעומר
...
26 Nissan, 5773 - Shmini,  - כ״ו ניסן תשע״ג - שמיני, י״א בעומר
...
6 Sivan, 5773, Shavuos - ו׳ סיוון תשע״ג, שבועות
7 Sivan, 5773, Shavuos - ז׳ סיוון תשע״ג, שבועות
...
17 Tammuz, 5773, Seventeenth of Tammuz - י״ז תמוז תשע״ג, שבעה עשר בתמוז
...
9 Av, 5773, Tishah B'Av - ט׳ אב תשע״ג, תשעה באב
...
15 Av, 5773, Tu B'Av - ט״ו אב תשע״ג, ט״ו באב
...

6 thoughts on “Using the Zmanim API 1.3.0 Jewish Calendar Code”

  1. אני מחפש כבר זמן רב…

    האם מישהו יוכל לעזור לי ולשלוח אלי סקריפט מוכן שמציג תאריך עברי – בעברית (עדיף עם הצגת חגים).

    אני מחפש כבר המון זמן ולא מצאתי משהו חופשי שניתן להשתמש בו.

    המייל שלי הוא segevm @ ג’ימייל.

    תודה רבה לכל העוזרים!

    1. Refael,
      There is indeed a way to do this, but the method name is not as clear as it should be. Construct a Date/Calendar and use the JewishDate.getTime() method to extract the Gregorian calendar. Here is a short example.

      JewishCalendar jd = new JewishCalendar(); // current date
      jd.setJewishDate(5729, JewishDate.SHEVAT, 21); // set the date to 21 Shevat, 5729
      Date date = jd.getTime(); // Feb 9, 1969 Gregorian
      

      Since the method was not easily discoverable, I renamed the method in the not-yet released next version to getGregorianCalendar() (it now returns a Calendar as opposed to a Date).
      In the updated code, the way to get the date would be:

      JewishCalendar jd = new JewishCalendar(); // current date
      jd.setJewishDate(5729, JewishDate.SHEVAT, 21); // set the date to 21 Shevat, 5729
      Calendar cal = jd.getGregorianCalendar(); // Feb 9, 1969 Gregorian
      Date date = cal.getTime(); // convert to Date if needed
      

Leave a Reply

Your email address will not be published. Required fields are marked *