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

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 Manat’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 the 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.


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

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

Parsha Code Restored to the KosherJava Zmanim Calendar API

Sunrise CalendarIn the Parsha Code Removed from KosherJava Zmanim Calendar API article posted two years ago, I documented the removal of the parsha code from the KosherJava Zmanim API due to licensing issues. I would like to announce that thanks to Yechiel Paricher, the zmanim library now supports a clean LGPL implementation. Yechiel’s Jan 17, 2019 pull request that was a port of his C libzmanim code, was finally merged on August 22nd, and over the past day, the old formatting code for parshiyos was restored after being changed to work with the new code. The new code not only restores the old functionality, but adds support for the special parshiyos of Shekalim, Zachor, Parah and Hachodesh. It also added support for Shabbos Mevorchim and Machar Chodesh.

FAQ: Chatzos Hayom VS Chatzos Halayla (Solar Noon VS Astronomical Midnight)

The sundial on the Zoharei Chama Synagogue as it appears on a 2014 Israeli stamp.


Is there a difference in time between the zmanim of chatzos hayom and chatzos halayla (astronomical midnight and astronomical high noon / midday) besides the obvious 12 hour difference?


I was recently asked by a developer why the KosherJava zmanim library does not have distinct calculations for chatzos halayla. The answer is that the zmanim API does indeed have the getSolarMidnight() calculation, but for the most part there is no real need for it. The time of chatzos halayla / midnight or chatzos hayom (solar transit / solar noon or midday) stays pretty constant from day to day. In the worst case scenario (on around December 22nd), the length of the solar day would increase by about 30.16 seconds from one day to the next. This does not change by location, but is the same anywhere in the world. This would mean that chatzos halayla could be a maximum of 15.08 seconds different than just using midday + 12 hours. This is something that should not really impact people. In addition, the developer in question does not even show seconds, making this a moot point. In short, chatzos on any given day should be considered accurate enough for both chatzos hayom and chatzos halayla of that day. It should be noted that the Mishnah Berurah quoting a number of achronim and the Shulchan Aruch Harav are of the are of the opinion that chatzos halayla is exactly 12 hours after chatzos hayom. The Mishnah Berurah states in הלכות הנהגת אדם בבקר א׳ ט׳

וזמן חצות הוא תמיד באמצעות הלילה ממש בכל מקום ואפילו בלילות הארוכות או הקצרות והיא י״ב שעות אחר חצי היום …

and the Shulchan Aruch Harav in הלכות השכמת הבוקר א׳ ח׳ states that

וזמן חצות לילה הוא שוה בקיץ ובחורף לעולם י״ב שעות אחר חצי היום שהוא אמצע הלילה ממש …

Chatzos Halayla on the Seder Night

MatzosThe time of year that the zman of chatzos has the greatest impact is during the Pesach seder when people want to finish the afikoman before chatzos. During this time of the year the solar days are shrinking slightly from day to day, resulting in chatzos halayla being slightly earlier than chatzos hayom + 12 hours. The difference in the length of the solar day from solar noon on erev Pesach to solar noon on the first day of Pesach ranges from 11 to 18 seconds depending on the year. On the very late erev Pesach on April 24 that last occurred in 1929 and 1967 and will next occur in 2043 and 2062 there is an 11 second difference. On the extremely early erev Pesach of March 25 that occurred in 1899 and 2013 and will occur next in 2089 (see Rabbi Dovid Heber’s Why is This Pesach the Earliest Since 1899?) there is an 18 second difference. This 5.5 to 9 second difference in the time of chatzos hayom VS chatzos halayla on erev Pesach is something that has almost no real world impact. It is interesting to note that based on the fact that the average Jewish year is slightly longer than the average solar year, the early March 25 erev Pesach will never happen again after 2089.

Equation of Time (EoT)

You may have expected that the longest day of the year – the summer solstice (June 20 or 21 depending on the year) would be the day with the earliest sunrise / netz (or hanetz) and latest sunset / shkiah (and therefore the day with the latest start of Shabbos). However the earliest sunrise actually occurs on or about June 14 (at latitude 40° – it varies slightly based on latitude), a week before the longest day, and the latest sunset occurs on or about June 28, a week after the summer solstice. As mentioned above, the length of the day that we know to be exactly 24 hours on a clock is actually only an average over the year. The length of the day varies slightly from day to day. This length of day range is from a minimum of 23 hours, 59 minutes and 38.64 seconds around September 17 to a maximum of 24 hours and 30.16 seconds around December 22 vs the previous day. This accumulated length of the day difference is known as the equation of time. While the day starts shortening after the solstice, chatzos (and by extension the entire day) is moving slightly forward as the solar day (midday to midday) grows at this time of the year, resulting in the day ending later despite it being shorter.

Note: The rest of the article is somewhat technical and can be skipped if you have no interest in detailed explanations as to why days differ in length.

The cause of the change is due to the following two main factors. The very minor impact of nutations (such as the Chandler wobble), axial precession and other factors are too small to make a practical difference in the EoT calculations.

The tilt of the Earth’s Rotational Axis

The tilt of the Earth’s rotational axis (also known as the axial tilt or the obliquity of the ecliptic) as compared to the plane of its orbit around the sun is one factor that impacts the length of the solar day. To understand this, note that the earth rotates on it’s axis in 23 hours 56 minutes and 4.1 seconds in relation to the stars. This is called a sidereal day. The remaining 3 minutes and 55.9 seconds or about 0.98° of rotation must be made up every earth day. Due to the 23.44° axial tilt, this 3 minutes and 55.9 seconds is only an average.

The sun’s path through the sky during the March equinox. The equatorial grid is blue, the ecliptic grid is orange and the ecliptic (the sun’s apparent path) is yellow.
During the equinoxes the earth’s 23.44° tilt results in the sun having to travel a drop farther (1.09° for every 1° of eastward travel) to cover a line of longitude, since its path is angled and traveling a drop northwards or southwards on its path west. This results in the day being slightly shorter, since the sun only travels about 0.9° along the equator as opposed to the average of 0.98° per day.
The sun’s path through the sky during the December winter solstice. The equatorial grid is blue, the ecliptic grid is orange and the ecliptic (the sun’s apparent path) is yellow.
In the winter and summer the sun’s path is parallel to the equator and has a direct east/west path. In addition, since the longitude lines are closer together at 23.44° degrees from the equator the sun travels further moving 1.09° parallel to the equator for every 1° of eastward travel. This results in a slightly longer day. A technical and detailed explanation can be found in Mike G’s explanation of the subject at the astronomy section of StackExchange (where the above Stellarium generated images are from) and in Art Carlson’s equation of time explanation.

The elliptical orbit of the earth

The elliptical orbit of the earth (or the eccentricity of the Earth’s orbit) is the second factor that impacts the length of the day. The earth’s orbit around the sun is an ellipse and not a perfect circle. Following Kepler’s second law, the earth moves slightly faster in orbit when it is closer to the sun, and slower when it is farther away. During the perihelion (it ranges between January 2 and 6 depending on the year) when the earth is closest to the sun at 91,402,500 mi / 147,098,070 km distance, it travels at 30.287 km/s, while at the aphelion (between July 3 and 7) when it is 94,509,100 mi / 152,097,700 km away, it travels at 29.291 km/s. In addition, the angular velocity of the sun is faster (in relation to the stars) when it is closer to earth. Despite it being somewhat counter-intuitive, the sun is closer to earth in middle of the northern hemisphere’s winter than during the summer. This non-uniform orbital speed impacts the length of the solar day.

The Accumulated Difference

This difference between our standard clock time and the time that would be based on the exact position of the sun in the sky accumulates and is referred to as the equation of time (EoT). Equation in this case refers to equality and not a mathematical equation (though the calculations certainly involve mathematical equations), and adding or subtracting this time allows us to sync solar time and clock time (mean solar time / universal time).
Please see the references section below for links that cover the topic in detail.

Note: This article is explained using a heliocentric based model. I would appreciate if my readers who follow the geocentric model would be able to post a detailed explanation of this article based on that view.

Thank you.


I would like to thank my son Shai for the detailed work on the technical part of this article.