Zmanim API 2.3.0 Released


The KosherJava Zmanim API version 2.3.0 was released on Dec 7th, 2021 ג׳ טבת תשפ״ב in Maven and GitHub. While there have been numerous releases over the years, this is the first release-related post since the v1.3.0 release in 2013. If you have not updated since that time, you can expect some changes. The most significant changes (besides a lot of new functionality) are the simple to fix breaking changes listed below.

New in Version 2.3.0

The list of significant changes in this and previous releases can be seen in the KosherJava Zmanim API changelog.

Breaking Changes since v1.3

Rav Moshe Feinstein’s Zmanim Added to the KosherJava Zmanim API


Rav Moshe Feinstein is of the opinion that chatzos is at a fixed time all year round and is calculated based on the location’s longitude (in Lakewood, NJ it is at 11:56am / 12:56pm during DST). See Igros Moshe Orach Chaim vol 4 no. 20 who states

והנה החצות לילה באמת לא משתנה כלל מימים הארוכים דקיץ לימים הקצרים חזודף אף לא לרגע אחד, למה שכתבתי בספרי אגדות משה על או״ח בסימן כ״ד שחצות היום הוא לעולם שוה שהוא כשבא השמש לאמצע הדרום וזה שוה בכל השנה רק ששני חצאי היום אינם שוים רק איזה ימים בשנה ולפעמים חצי הראשון גדול ולפעמים חצי השני גדול עיי״ש, וכן קבלתי גם מאבי מורי זצללה׳׳ה.

See the Igros Moshe for more details. The Aruch Hashulchan in Orach Chaim 233 no. 14 also calculates chatzos at a fixed time all year.

ודע דחצות היום תמיד שוה בקיץ ובחורף כשיכה המורה שעות י״ב אז הוי חצות היום וכן בלילה שהרי השעות שנתוספו או נתקצרו חציים מקודם חצות וחציים מלאחר חצות וא׳׳כ ממילא דהחצות לעולם עומדת בשוה

Rav Moshe also bases other zmanim calculations on this fixed local chatzos. As opposed to calculating shaaos zmaniyos from beginning to the end of a day, Rav Moshe calculates a number of zmanim based on half of the day starting or ending at fixed local chatzos (see Igros Moshe Orach Chaim vol 1, no. 23).

ומש״כ ידידי שהלוח של הישיבה אינו מדוקדק, הנה הוא בדיוק גדול ונכתב על דעתי. והטעם דהחצות של היום שהוא כשבא השמש באמצע הדרום שוה לעולם, אבל שני חצאי היום אינם שוים רק איזה ימים בשנה ולפעמים חצי הראשון גדול ולפעמים חצי האחרון. ולכן בין לקולא בין לחומרא מסתבר שנחלקו שש שעות עד חצות ושש שעות מחצות עד הערב. ולכן מש״כ ידידי שהוא שבשתא וטעות לא דבר נכונה שהוא אמת גמור וליכא ע״ז שום קושיא.

These zmanim are used in Mesivta Tiferet Yerushalayim (MTJ), Yeshiva of Staten Island and Camp Yeshiva of Staten Island. Code to calculate these Rav Moshe zmanim is now part of the latest v2.3.0 release of the KosherJava Zmanim API.
The following new zmanim are now included in the API:

Sample Usage

For developers, here is sample code that calculates the new zmanim. This should allow many zmanim apps to add Rav Moshe Feinstein’s zmanim with very little effort.

String locationName = "145 E Broadway, New York, NY";
double latitude = 40.7138;
double longitude = -73.9913;
double elevation = 11;
TimeZone timeZone = TimeZone.getTimeZone("America/New_York");
GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, timeZone);
ComplexZmanimCalendar czc = new ComplexZmanimCalendar(location);
czc.getCalendar().set(1986, Calendar.MARCH, 23); //Rav Moshe's petirah
System.out.println("Sof zman shma alos 18° to fixed local chatzos: " + czc.getSofZmanShmaMGA18DegreesToFixedLocalChatzos());
System.out.println("Sof zman shma alos 16.1° to fixed local chatzos: " + czc.getSofZmanShmaMGA16Point1DegreesToFixedLocalChatzos());
System.out.println("Sof zman shma alos 90 to fixed local chatzos: " + czc.getSofZmanShmaMGA90MinutesToFixedLocalChatzos());
System.out.println("Sof zman shma alos 72 to fixed local chatzos: " + czc.getSofZmanShmaMGA72MinutesToFixedLocalChatzos());
System.out.println("Sof zman shma sunrise to fixed local chatzos: " + czc.getSofZmanShmaGRASunriseToFixedLocalChatzos());
System.out.println("Sof zman tfila sunrise to fixed local chatzos: " + czc.getSofZmanTfilaGRASunriseToFixedLocalChatzos());
System.out.println("Mincha gedola 30 minutes after fixed local chatzos: " + czc.getMinchaGedolaGRAFixedLocalChatzos30Minutes());
System.out.println("Mincha katana fixed local chatzos to sunset: " + czc.getMinchaKetanaGRAFixedLocalChatzosToSunset());
System.out.println("Plag hamincha fixed local chatzos to sunset: " + czc.getPlagHaminchaGRAFixedLocalChatzosToSunset());
System.out.println("Tzais 50 minutes after sunset: " + czc.getTzais50());

Calculating other fixed local chatzos based zmanim not included in the library (and not necessarily endorsed by this shitta) are very simple with the generic getFixedLocalChatzosBasedZmanim(Date startOfHalfDay, Date endOfHalfDay, double hours) method built to simplify calculating these zmanim. Here are a few examples.

//4 hours into a day based on half the day from alos 18° to fixed local chatzos
System.out.println("Sof zman tfila 18° to fixed local chatzos: " + czc.getFixedLocalChatzosBasedZmanim(getAlos18Degrees(), getFixedLocalChatzos(), 4); 
//plag hamincha based on the second half of the day starting at fixed local chatzos and ending 50 minutes after sunset
System.out.println("Plag hamincha fixed local chatzos to tzais 50 minutes: " + czc.getFixedLocalChatzosBasedZmanim(getFixedLocalChatzos(), getTzais50(), 4.75); 

I would like to thank Avraham David Gelbfish who requested this addition and provided instructions on the proper calculations used by these yeshivos in calculating the zmanim.

The Yereim’s Bein Hashmashos

Rabbi Eliezer of Metz (known by his acronym The רא״ם Re’em), a disciple of Rabbeinu Tam, in his Sefer Yereim ספר יראים chapter 274, states that bein hashmashos starts the time it takes to walk three quarters of a mil before sunset, and ends at sunset.

פירוש משתשקע החמה דר׳ יהודה ור׳ נחמיה משמתחלת לשקוע שנוטה מעט ומכירים העולם שרוצה להכנס בעובי הרקיע … ולשון משתשקע משמע הקדמה … וכן נראה לי עיקר דמשתשקע החמה הוא קודם שקיעת החמה דעולא ולא כדברי רבינו יעקב … ואין להקפיד על צאת הככבים … אע״ף שאין הכוכבים נראים … שלילה גמור הוא כפירושי.

The Yereim’s opinion is brought down by other Rishonim including the Mordechai and Rav Alexander Suslin HaKohen in his Sefer Agudah. The Yereim is mentioned by the Bach as a reason for the minhag of starting Shabbos early. The Yereim’s times are not brought down by the poskim lehalacha.

The Time to Walk a Mil

The time to walk a mil is based on the Gemara in Pesachim 93b – 94a. The time ranges in the poskim and includes 18, 22.5 and 24 minutes. Three quarters of these mil times would be 13.5, 16.875 and 18 minutes. It should be noted that the Yereim is of the opinion that a mil is 24 minutes. The above mentioned Mordechai who quoted the Yereim is also of the same opinion. We will hopefully discuss in detail the various opinions on the time to walk a mil in a future article.

The Addition of the Yereim’s Times to the KosherJava Zmanim Library

As of the 2.1.0 release of the KosherJava zmanim library, the Yereim’s bein hashmashos times have been added to the KosherJava zmanim library/API. There are six variants of these zmanim that were added. These include the three exact minute offsets mentioned above, as well as the conversion of these three times to degrees (elevation angle, or solar zenith angle). The only prior degree based time for the Yereim that I am aware of is in Rabbi Yedidya Manet’s Zmanei Halacha Lema’aseh (זמני ההלכה למעשה מהרב ידידיה מנת). The Zmanei Halacha Lema’aseh charts calculate bein hashmashos in degrees based on the 18 minute (3/4 of a 24 minute mil, see p. 27 in the 4th ed. published in 2005), but does not clarify the degrees used. At Rabbi Yaakov Shakow’s recommendation, I used the refraction value of 31/60 or 0.516° that exists in Israel, as opposed to the global average of 0.566°. This more stringent refraction is mentioned in the Zmanei Halacha Lema’aseh (p. 11) and used in the לוח עתים לבינה Luach Itim Lebinah. I also slightly rounded the times. These small tweaks resulted in a trivial maximum 19 second chumra vs the non-rounded global average refraction. The resulting degrees of elevation angle for the Yereim’s bein hashmashos are 2.1°, 2.8° and 3.05°. Solar zenith angles are traditionally calculated using the sun’s position without adjusting for refraction and without accounting for the solar radius (i.e. it is the position of the center of the sun in a vacuum). This does not impact the calculated time, it is simply the convention used. In the upcoming 8th edition of הרב דוד יהודה בורשטין Rabbi Yehuda Burstein’s זמנים כהלכתם / Zmanim Kehilchasam he mentions that

הזמן הנ״ל של 18 דקות לפני השקיעה המישורית הוא הזמן רק במרכז א״י ביום הבינוני כנ״ל, ובכל מקום בכל יום מחשבין זאת לפי שיטת המעלות, דהיינו דבודקים כמה מעלות מעל האופק נמצאת השמש במרכז א״י ביום הבינוני 18 דקות לפני השקיעה המישורית, ואותו מספר מעלות של השמש מעל האופק בכל מקום בכל יום הוא הזמן של ״היראם״. ועוד יש להוסיף זמן ל״תוספת שבת״, ובזה יוצא ידי כל שיטות הראשונים ואשרי חלקו.

A future article will address the proper date to use for converting minute-based times to degrees below (or above) the horizon and show how to use the KosherJava Zmanim code to calculate this.
I would like to thank Rabbi Yaakov Shakow for his help and suggestions.

Sample Code

Below are code examples for all six variants of the Yereim’s Bein Hashmashos (spelled BainHashmashos in the code).

GeoLocation yerushalayim = new GeoLocation("Jerusalem, Israel", 31.778, 35.2354, 0, TimeZone.getTimeZone("Asia/Jerusalem"));
ComplexZmanimCalendar czc = new ComplexZmanimCalendar(yerushalayim);
Date bh18Min = czc.getBainHasmashosYereim18Minutes();
Date bh3Pt05Deg = czc.getBainHasmashosYereim3Point05Degrees();
Date bh16Pt875Min = czc.getBainHasmashosYereim16Point875Minutes();
Date bh2Pt8Deg = czc.getBainHasmashosYereim2Point8Degrees();
Date bh13Pt5Min = czc.getBainHasmashosYereim13Point5Minutes();
Date bh2Pt1Deg = czc.getBainHasmashosYereim2Point1Degrees();

SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd h:mm:ss a z"); //set the output format
sdf.setTimeZone(czc.getGeoLocation().getTimeZone()); //set the formatter's time zone
System.out.println("Bein Hashmashos 18 min:     " + sdf.format(bh18Min));
System.out.println("Bein Hashmashos 3.05°:      " + sdf.format(bh3Pt05Deg));
System.out.println("Bein Hashmashos 16.875 min: " + sdf.format(bh16Pt875Min));
System.out.println("Bein Hashmashos 2.8°:       " + sdf.format(bh2Pt8Deg));
System.out.println("Bein Hashmashos 13.5 min:   " + sdf.format(bh13Pt5Min));
System.out.println("Bein Hashmashos 2.1°:       " + sdf.format(bh2Pt1Deg));

The output of the above code (assuming that the calendar was set to March 16, 2020).

Bein Hashmashos 18 min:     2020-03-16 5:29:58 PM IST
Bein Hashmashos 3.05°:      2020-03-16 5:29:40 PM IST
Bein Hashmashos 16.875 min: 2020-03-16 5:31:05 PM IST
Bein Hashmashos 2.8°:       2020-03-16 5:30:51 PM IST
Bein Hashmashos 13.5 min:   2020-03-16 5:34:28 PM IST
Bein Hashmashos 2.1°:       2020-03-16 5:34:09 PM IST

KosherJava Zmanim Library Package Name and Build Process Update


The KosherJava zmanim library originally went live in 2004. There was an existing C/C++ zmanim project by Ken Bloom hosted on SourceForge (that was at the time the equivalent of what GitHub is today). The Java package structure name net.sourceforge.zmanim was based on the one used by Ken’s project (despite not being hosted there), and remained that way for 16 years.
On August 3, 2020, Eli Julian modernized the library’s build process from the previously used Ant, to Maven & Gradle. This change simplified the workflow for many developers using the zmanim API. As part of the change, the package name was updated to com.kosherjava.zmanim. The KosherJava zmanim Maven / Gradle artifacts are available at the KosherJava zmanim Maven Central page. A direct Jar download is available at Maven Central (see the KosherJava Downloads page for instructions). The old code was branched into zmanim-1.5 and will allow people who do not want to upgrade to continue to use the old structure (and Ant build process) while continuing to receive emergency bug fixes. This will allow the codebase to use more modern Java language features, without impacting users who want to remain on the legacy code. The new code has a minimum Java 8 requirement (a version released in March 2014). Releases based on the new build process will use SemVer (Semantic Versioning) to make things simpler for developers.
The upgraded build process also allowed automated GitHub’s CodeQL vulnerability scanning for the KosherJava Zmanim project.
You can add the KosherJava zmanim library as a Maven or Gradle dependency. For Maven add the following to your pom.xml.

<dependency>
  <groupId>com.kosherjava</groupId>
  <artifactId>zmanim</artifactId>
  <version>2.0.3</version>
</dependency>

For Gradle, add the following to your build.gradle file.

implementation group: 'com.kosherjava', name: 'zmanim', version: '2.0.3'

Latest Kiddush Levana Time – Location, Location, Location

The full moon visible from the Inbal hotel sukkah.

In the previously published Zmanim For Kiddush Levana Before Shavuos 5778 article, we demonstrated how location plays a key role in the earliest time one can recite Kiddush Levana / קידוש לבנה. This article will focus on the Sof Zman Kiddush Levana, or the latest that one can recite Kiddush Levana. In the past we posted the technical Calculating Kiddush Levana Times Using the Zmanim API post, with a simple example of using the KosherJava Zmanim API to calculate Kiddush Levana. Here is a slightly more complex example.
The Bach on the Tur Hilchos Kiddush Hachodesh (Orach Chayim 426 תכ”ו) discusses not reciting Kiddush Levana on Yom Tov.

גם נוהגים שאין מקדשין אותה במ״ש שחל בו י״ט כי כן כתב מהרי״ל בסוף הלכות שבועות ובשנת ש״ץ לא היתה נראה הלבנה במוצאי י״כ וגם אח״כ לא היתה נראה עד ליל ט״ו והיינו מקדשין אותה בליל י״ט ולא חששנו על החילוקים כי אין זה אלא קפידא בעלמא כאילו יצא מחוץ לתחום למעלה מעשרה במחשבה להקביל פני השכינה ואין להקפיד אלא לכתחלה דאפשר לקדשה אח”כ כגון שבועות כשחל א״ב אבל בליל ט״ו דסוכות דלא אפשר לברך בלילה שלאחריו דכבר נתמלא פגימתה יש לברך בליל ט״ו

He writes that in Tishrei 5390 (1629) there was cloud cover from Yom Kippur until the first night of Succos. The Bach who was the Rabbi in Kraków at that time (see the Be’er Haitev 426:5), writes that they said Kiddush Levana on the first night of Sukkos. This is right after he mentioned that it is our custom not to recite Kiddush Levana after halfway between molad and molad (following the Maharil and Rema, and not the Mechaber who allows a little extra time). Was tzais (the earliest time to recite Kiddush Levana), on the first night of Succos in Kraków that year (5390 / 1629) after the midpoint between molad and molad? Is the Bach saying that in this case bedieved you should still recite Kiddush Levana, or is he just saying that it can be said on Yom Tov when waiting until after Yom Tov will be too late?

The Impact of Calendar Dechiyos / דחיות

The day of the molad of Tishrei is the target day for the first day of Rosh Hashana. However, the Jewish calendar has four rules that delay the start of the Jewish year by a day or two (in a case of two delays combining), a subject that we will hopefully cover at some point – עוד חזון למועד. If not for these delays known as dechiyos that occur about 60% of all years, the 15th night of the month of Tishrei, would always be early enough to recite Kiddush Levanah. The average lunar month is a drop over 29 and a half days (29 days, 12 hours, 44 minutes and 3.3 seconds), so the halfway point that is the end of the earlier time quoted by the Bach would be 14 days, 18 hours and 22 minutes after the molad. The calculation below shows that in the case of 15 Tishrei, 5390 (the evening of Oct 1, 1629), even the earlier zman for sof zman Kiddush Levana did not happen until the morning of the first day of Succos. The molad of Tishrei that year was about 2.5 hours before the day’s end. This resulted in a dechiya of Molad Zaken / מולד זקן. This delayed Rosh Hashanah by a day pushing it from Monday to Tuesday. There was no dechiya of Lo ADU Rosh / לא אד״ו ראש, so the delay was not as long as it could have been (had there been a combination of the two dechiyos). Sunset on the first night of Sukkos that year in Krakow was at 5:18 pm (using standard time), and the moon rose at 5:54 pm, so they were able to recite Kiddush Levana that night.

Despite dechiyos, the time of tzais in Krakow is before sof zman Kiddush Levana on the first night of Succos approximately 73% of the time, making the ability to recite Kiddush Levanah on the first night of Sukkos for the longitude of Krakow (that is close to Yerushalayim) more common than not. As you will see below, the farther west you go, the less likely it is to happen.

Sof Zman Kiddus Levana Around the World

Being that Sof Zman Kiddush Levana is a fixed time globally, and can’t be said before local tzais, the farther west you are, the less of a probability you have of encountering a late Kiddush Levana. Conversely, the farther east you are, the greater your probability is of encountering a late Kiddush Levana. The chart below was inspired by Rabbi Dovid Heber’s example in his sefer Shaarei Zmanim of the rare ability to recite Kiddush Levana on the 17th of the month in Anadyr, Russia. This town is at the far eastern portion of Russia, not far from the International Date Line. The chart shows the percentage of times that Sof Zman Kiddush Levana in Tishrei and the annual average for various places around the world occurs after tzais (calculated as 8.5°) on the 15th, 16th and 17th of the month.

15thט״ו16thט״ז17thי״ז
LocationתשריAllתשריAllתשריAll
Anadyr, Russia91%57%46%18%N/A0.2%
Sydney, Australia88%73%42%21%N/AN/A
Yerushalayim75%57%24%8%N/AN/A
Krakow, Poland73%55%22%7%N/AN/A
Lakewood, NJ62%41%8%1.6%N/AN/A
Los Angeles, CA56%35%3%0.7%N/AN/A
Kurima Island, Japan
(Chazon Ish)
39%18%N/AN/AN/AN/A

Molad Calculation Code Sample

The code below shows rudimentary use of the Jewish Calendar functionality and molad retrieval for the historical date of the Bach’s 1629 Sukkos night kiddush levanah.

int month = JewishDate.TISHREI;
int year = 5390;
JewishDate erevSukkos = new JewishDate(year, JewishDate.TISHREI, 14);
JewishDate molad = JewishDate.getMolad(year, month);
Date tchilas3Days = JewishCalendar.getTchilasZmanKidushLevanah3Days(year, month);
Date tchilas7Days = JewishCalendar.getTchilasZmanKidushLevanah7Days(year, month);
Date sofZmanBetweenMoldos = JewishCalendar.getSofZmanKidushLevanahBetweenMoldos(year, month);
Date sofZmanKidushLevanah15Days = JewishCalendar.getSofZmanKidushLevanah15Days(year, month);
TimeZone krakowTZ = TimeZone.getTimeZone("Europe/Warsaw");
SimpleDateFormat sdf = new SimpleDateFormat("MMM dd, yyyy 'at' HH:mm:ss z");
SimpleDateFormat dayFormat = new SimpleDateFormat("MMM dd, yyyy");
sdf.setTimeZone(krakowTZ);
System.out.println("Molad: " + molad + " / " + dayFormat.format(molad.getTime()) + ", day of week: "
		+ molad.getDayOfWeek() + ", Hours: " + molad.getMoladHours() + ", minutes: " + molad.getMoladMinutes()
		+ ", Chalakim: " + molad.getMoladChalakim());
System.out.println("Tchilas Zman Kidush Levanah 3 Days: " + sdf.format(tchilas3Days));
System.out.println("Tchilas Zman Kidush Levanah 7 Days: " + sdf.format(tchilas7Days));
System.out.println("Erev Succos: " + erevSukkos + " / " + dayFormat.format(erevSukkos.getTime()));
System.out.println("Sof Zman KidushLevanah Between Moldos: " + sdf.format(sofZmanBetweenMoldos));
System.out.println("Sof Zman Kidush Levanah 15 Days: " + sdf.format(sofZmanKidushLevanah15Days));

The output in Central European Time (CET) is:

Molad: 29 Elul, 5389 / Sep 17, 1629, day of week: 2, Hours: 15,
        minutes: 46, Chalakim: 5
Tchilas Zman Kidush Levanah 3 Days: Sep 20, 1629 at 14:25:19 CET
Tchilas Zman Kidush Levanah 7 Days: Sep 24, 1629 at 14:25:19 CET
Erev Succos: 14 Tishrei, 5390 / Oct 01, 1629
Sof Zman KidushLevanah Between Moldos: Oct 02, 1629 at 08:47:21 CET
Sof Zman Kidush Levanah 15 Days: Oct 02, 1629 at 14:25:19 CET

Odds & Ends

While Tishrei has much higher odds than most months for a late Sof Zman Kiddush Levana, Shevat is very close to Tishrei, and sometimes exceeds it. Cheshvan and Kislev are the only variable length Jewish months. In a chaser (Deficient / short) year they will both have the short month length of 29 days. The months of Cheshvan and Kislev are followed by Teves that is always 29 days. With the possibility of three 29-day months in a row and being in the winter with early tzais times, the month of Shevat is the most likely to have a very late sof zman Kiddush Levana, as pointed out by Rabbi Heber in his Shaarei Zmanim.

The reason that Anadyr only has a 57% chance of being able to recite Kiddush Levana year-round on the 15th VS 73% in Sydney, even though Anadyr is 3% more likely to have Kiddush levana on the 15th of Tishrei, is due to the high latitude of Anadyr (64.7° N) that results in 25.4% of the months not having tzais on the 15th.

The closest case to almost not being able to recite Kiddush levanah on the 15th of Tishrei without dechiyos would be in a location immediately to the east of the Chazon Ish dateline such as Kurima Island on a year when the molad was exactly at sunset in Yerushalayim and the true opposition (full moon) was much earlier than the average opposition, causing the moon to rise after sof zman kidush levana. Calculations show that this would never actually happen on Sukkos though it is likely to occur on Pesach since the molad of Nisan is much more likely to be before Rosh Chodesh.