Time Zone Database – A Critical But Overlooked Zmanim Component

An important aspect of calculating accurate zmanim, is ensuring that the timezone information on the computer generating the zmanim is kept up to date. The volunteer maintained IANA time zone database (also known as the tz, zoneinfo or Olson database) is used globally by computers to store time zone information. Failure to keep up to date with the latest database will result in potentially generating zmanim that can be off by an hour or more in parts of the world. This time zone database is updated multiple times a year as locations around the world change their time zone information. Often changes are to the start and end of DST in various zones, but it sometimes includes year-round changes and newly introduced time zones that have rules differing from the geographic area around them. There is a general lack of awareness by zmanim software developers and system maintainers hosting zmanim apps, of the criticality of keeping this data up to date. A lack of keeping it up to date can result in the possibility of significant issues in zmanim calculations. Subscribing to the tz announcements mailing list will keep you up to date on the latest zone changes.

Timelines for Time Zone Data Updates

There are times when updates to the database are not released until after the changes take effect, and there are cases where the announcements are made very shortly before they take effect. An example of this was Lebanon’s 2023 change and reversal. On Mar 23, 2023 Lebanon announced that the DST that had been scheduled to start 2 days later on Mar 25 was being postponed to Apr 20. The IANA time zone database 2023b was released a day later on Mar 24 (2 days after the 2023a release). On Mar 27 they announced that they were moving to DST on Mar 29. On Mar 27, 2023c was released that restored an identical version to what had been released in 2023a.
Here is a timeline from the 2024a update for Kazakhstan (that has a small Jewish community impacted by the change). The change unified time zones for the entire country (that stretches 3,000 km /1,900 mi from east to west and geographically spans 4 time zones) from two (UTC+6 and UTC+5) to one UTC+5 zone. The timeline shows that despite being on top of things, you can’t always ensure that you are up to date.

  • Oct 19, 2023 – Discussions started about a proposed change to unify Kazakhstan on a single time zone. On Nov 12, 2023 – A draft decree about the change was published.
  • Dec 7, 2023 – The Kazakh Ministry of Trade and Integration announced the decree formalizing the changes.
  • Jan 19, 2024 – The changes were brought to the attention of the IANA Time Zone Database maintainers. It is not unusual for a delay like this in notifying the maintainers of a change.
  • Feb 1, 2024 – The time zone data change was released as 2024a.
  • Feb 2, 2024 – PECL timezonedb package was released.
  • Feb 4, 2024 – Moment.js‘s Moment Timezone releases v0.5.45 with the change.
  • Feb 14, 2024 – Android Mainline PR is merged. It would be available to most Android 10 devices within 24 hours. Older Android versions will have to wait for the next release.
  • Mar 1, 2024 – At the stroke of midnight, the clocks in part of Kazakhstan rolled back to Feb 29 at 11pm, resulting in a 25 hour leap year leap day.
  • Mar 6, 2024 – Node.js code was initially updated on the main branch on Feb 15 and an issue was opened on March 1 to have a release with the updated zone information. The non-LTS version 21.7.0 with the change was released om March 6. LTS versions 20.0.12.0 and 18.20.0 with the changed were released on March 26, 26 days after it took effect.
  • Mar 26, 2024 – Windows made the first update available via the March 2024 non-security preview update (that most do not install), 26 days after the change took effect.
  • Apr 9, 2024 – General availability of the Windows patch was released, 40 days after it took effect.

Updating Operating Systems and Various Languages

Below are the basics for keeping your system’s time zone database up to date. Note that there are times when the announcements of changes do not give much warning, and it is not always possible to keep perfectly up to date on some platforms. If you have information on languages and systems not covered here, please post information in the comments section.

  • Windows – Keep your Windows Updates up to date with optional updates. Systems set for security updates only, will never receive this update. See the information above on the windows portion of the timeline section.
  • Linux – Patches are usually available immediately after the release by the IANA team. Here is some info, but be sure to read the manuals before trying things. Ubuntu you would run something like sudo apt update && sudo apt upgrade -y tzdata. For Redhat it would involve something like sudo dnf update && dnf upgrade -y tzdata.
  • Android devices receive timely time zone updates for the devices current location, that will often not address issues in updating zone information for other locations. When generating zmanim for another location, care must be taken to ensure that the underlying zone database is up to date. Note that as of Android 10 (released in Sep, 2019 and currently only on about 20% of devices), the TZDB module was enhanced to update via the Mainline modules system that speeds up deployment of the updates. The Android tzdata process was enhanced late in 2023 to separate this to a standalone process that can be quickly updated multiple times a year without having to wait for other Mainline updates. Developers who want to package their own database to support older Android devices can package the Joda-Time for Android with their app, but they would have to ensure that they update their app every time a new zone database is released.
  • Java provides a TZUpdater tool (download) that can can be used to update the time zone database in Java. Having the latest Java release is not reliable enough, since there are time zone changes more often than the twice yearly release (though minor versions are updated more often).
  • JavaScript / TypeScript that use Moment would have to update their package.json and run npm install to receive updates. Luxon seems to use the operating system’s tzinfo. See info for Linux and Windows above. For other packages or libraries, research is needed.
  • PHP out of the box only updates the zone data on new releases, They maintain the timezonedb PECL package to deal with cases (like ours) where up to date zone data is needed, but it requires regular updates.
  • Python uses the operating system’s tzinfo. See info for Linux and Windows above. Alternatively, use pytz.
  • Ruby uses the operating system’s tzinfo. See info for Linux and Windows above.
  • Go uses the operating system’s tzinfo. A standalone copy can optionally be embedded in the Go executable.
  • iOS – I was unable to find any reliable information on the subject. Apple support declined to provide any information on the subject besides confirming that they push time zone updates in a timely manner.

For many systems, cron or other jobs are needed to keep the database updated on a regular schedule. For many, a restart of the system may be required.

Warning: Inexpensive shared hosting poses significant challenges to keeping your system zone database current. There are many aspects that you have no control over, and keeping the time zone database up to date is often not high on the agenda of risk-averse shared hosts.

Additional Complexities with Mobile Devices

There is an additional set of complexities for time zones for mobile devices. While this affects Macs and possibly Windows, very few if any are using native zmanim apps on those platforms.

  • One of the more common complaints about incorrect zmanim end up being caused by the device being set to the incorrect time zone. Most devices change their zone automatically, but some users manually change things and when they travel to a different zone without changing the zone, it results in incorrect zmanim. Mobile developers should explore detecting that the time zone on the device is different than the expected time zone, and alert the user to check the devices time zone setting, while ensuring that it does not have issues when there is no cellular signal (such as when flying).
  • Users in Israel may find themselves in areas where the phone sets the zone to Asia/Hebron or Asia/Gaza. Those areas have different DST rules than Israel, and will cause issues when the DST rules differ. A way to handle this situation in an app is to ensure that the app detects the setting of these two zones and use Asia/Jerusalem. I am unsure if Israeli cell providers return the expected zone setting in the West Bank (or Gaza).

Here is sample java.time.ZoneId code to address the second issue.

ZoneId zi = ZoneId.of("Asia/Hebron");
if((zi.getId().equals("Asia/Gaza") || zi.getId().equals("Asia/Hebron"))){
    zi = ZoneId.of("Asia/Jerusalem");
}

Historical List of Time Zone Changes

To give an idea of the scope of time zone changes (that some assume are rare or trivial), here is a list of changes to the database. The year 2009 sticks out with 21 published changes to the database, but as you can see, there are many years numerous changes published. This list excludes technical, historical (where there are corrections to the history of time zone changes years after the fact) and some irrelevant changes. There are many examples where a location made changes more than once a year, and those are not broken out. You can see some patterns here of countries that change very often. Ramadan is a cause of many changes in Muslim countries.

Year Updates Updated areas and Zones
2024 2 Kazakhstan (unified Asia/Almaty and Asia/Qostanay). Improve historical data for Mexico, Mongolia, and Portugal.
2023 4 Egypt, Palestine, Morocco, much of Greenland and Lebanon.
2022 7 Chile, Palestine, Iran, Jordan, Syria, Mexico (except near the US border), Chihuahua, Fiji, northern edge of Chihuahua, much of Greenland).
2021 5 South Sudan, Jordan, Samoa, Fiji, Palestine
2020 6 Morocco, Canada’s Yukon, Casey (Antarctica), Fiji, Palestine, Volgograd.
2019 3 Metlakatla, Palestine, Brazil, Fiji, Norfolk Island.
2018 8 São Tomé and Príncipe, Brazil, Palestine, North Korea, Volgograd, Fiji, most of Chile, Morocco, Qyzylorda (Kazakhstan) and Metlakatla, Alaska. New zone Asia/Qostanay.
2017 3 Mongolia, Chile, Haiti, Northern Cyprus, Fiji, Namibia, Sudan, Tonga, Turks & Caicos.
2016 10 America/Cayman, Asia/Chita, Palestine, Asia/Tehran, America/Metlakatla, Asia/Sakhalin, Azerbaijan, Chile, America/Caracas, Asia/Magadan, Africa/Cairo, Asia/Novosibirsk, Turkey, Pacific/Tongatapu, Tonga and Antarctica/Casey. New zones Europe/Astrakhan and Europe/Ulyanovsk, Asia/Barnaul, Asia/Tomsk, Europe/Kirov, Asia/Famagusta, Europe/Saratov.
2015 7 America/Cancun, Chile, Mongolia, Palestine, Egypt, Morocco, North Korea, Moldova Turkey, Norfolk, Fiji’s, Fort Nelson (BC, Canada).
2014 10 Turkey, Fiji, Crimea, Egypt, Morocco, Russia (Magadan Oblast, Zabaykalsky Krai, Chukotka Autonomous Okrug, Kamchatka Krai, Kemerovo Oblast, Samara Oblast), Udmurt Republic, Turks & Caicos, Fiji, Quintana Roo (Mexico), Chile. New zones Asia/Chita, Asia/Srednekolymsk and Pacific/Bougainville
2013 9 Chile, Haiti, Paraguay, Morocco, Palestine, Fiji, Tocantins, Israel, Jordan, Libya, Western Sahara, Acre, western Amazonas, Cuba. New Zones Asia/Khandyga, Asia/Ust-Nera, Europe/Busingen
2012 10 Armenia, Tokelau, Chile, Falkland Islands, Cuba, Morocco, Haiti, Fiji, Samoa, Palestine, Bahia, Tocantins, Israel, Jordan, Libya. New zone America/Creston
2011 14 America/North_Dakota/Beulah (Mercer County, North Dakota, Chile, Annette Island (Alaska), Samoa, Cuba, Turkey, Morocco, Palestine, Falkland Islands, Egypt, Russia, Newfoundland, Belarus, Ukraine, Tiraspol (Moldovia), Bahia (Brazil) and Fiji. New Africa/Juba (South Sudan) zones.
2010 15 Mexico, Paraguay, Bangladesh, Samoa, Fiji, Chile, Dhaka, Australian (Antarctic), Kamchaatka, Anadyr, Samara, Tunisia, Pakistan, Morocco and Egypt. New “Bahia_Banderas” time zone added.
2009 21 Cuba, Morocco, Tunisia, Argentina and Syria, Palestine, Jordan, Pakistan, Egypt, Bangladesh, Dhaka, Mauritius, Samoa, Fiji and Resolute
2008 9 Chile, Cuba, Argentina, Morocco, Pakistan, Choibalsan (Mongolia), Brazil, Iraq (abandons DST). Mauritius’s 2008 DST experiment, and some localized Brazilian time zone realignments.
2007 11 Asmara, Easter Island, Syria, Honduras, New Zealand, Australia (for 2008), America/Indiana, Brazil, Egypt, Iran, Venezuela, Cuba and Argentina.
2006 16 America/Indiana and America/New Brunswick (Canada), Haiti, Sri Lanka, Egypt, Syria, Uruguay, Honduras, Bermuda, Moncton, Blanc-Sablon and Western Australia.
2005 14 Uruguay, Kyrgyzstan …

FAQ: Location Precision for Zmanim Calculations

While overly broad ZIP code based zmanim geolocation can be an issue in calculating zmanim accurately, going overboard in geolocation precision and accuracy for zmanim is a (harmless) waste of time.
Let’s start with the basics. Asking what the zmanim are for the USA is too broad of a location. Narrowing it down to a state is also too broad since zmanim at one side of the state are likely to be different than the other side. How small (or precise) does an area have to be for the zmanim calculated to be considered accurate? The location of zmanim are calculated based on degrees of longitude (east to west) and latitude (north to south).

The earth’s circumference at the equator is about 40,000 km (about 25,000 mi). There are 360 degrees of longitude around the world (The 0° line is centered on the Royal Greenwich Observatory in England, and longitude lines extend 180° to the west and -180° to the east). For simplicity we will deal with longitude degrees at the equator. If we divide the earth’s circumference by 360°, each degree of longitude will be 111 km (69 mi) apart. The sun’s path travels 1° of longitude in 4 minutes, so calculating zmanim with one degree accuracy (no decimal points such as the latitude of 40° and longitude of -74° for Lakewood, NJ, a point in the Atlantic about 3 mi off the coast of Toms River, NJ) results in zmanim accurate to 4 minutes in each direction or an 8 minute spread, not quite accurate enough to rely on. Moving to one decimal point will pinpoint the location for zmanim calculation to an accuracy of 11 km or 48 second accuracy. That is close to being accurate enough, especially given the inaccuracy of solar time calculations resulting from hard to predict refraction caused by varying atmospheric conditions. However, this should be avoided. Adding a second decimal point (such as the latitude of 40.09° and longitude of -74.22° for Lakewood, NJ – a spot at the edge of Lake Carasaljo in Lakewood) would have a precision of about 4 seconds, more than enough accuracy for zmanim.
A concrete example of how zmanim differ from place to place in a small area would be the difference between Beth Medrash Govoha (BMG) and the Westgate Bais Medrash in Lakewood. They are 2.7 km (1.69 mi) or a drop more than 0.01° apart and calculations show that there is about a 6 second difference in sunrise and sunset times between these two locations.

From time to time I am contacted by developers with zmanim related technical questions. Debugging their issues often requires information on the latitude and longitude that they are using to try and replicate the issue. Often the latitude and longitude are sent with multiple decimal points. The most extreme was 14 decimal points. To understand the ridiculousness of this level of precision, see the table below. To read more on the subject, see the Stack Exchange page Measuring accuracy of latitude and longitude? and the xkcd cartoon on the subject.

Decimal places Degrees Distance Notes
0 1 111 km A state or small country
1 0.1 11.1 km City
2 0.01 1.11 km Neighborhood
3 0.001 111 m A specific cul-de-sac
4 0.0001 11 m A corner of a house
5 0.00001 1.1 m A person in a room
6 0.000001 11 cm A small siddur
7 0.0000001 1 cm The size of Waldo on a page
8 0.00000001 1 mm A grain of sand
9 0.000000001 111 μm The width of a hair
10 0.0000000001 11 μm A grain of pollen
11 0.00000000001 1 μm A smoke particle
12 0.000000000001 111 nm The width of a COVID virus
13 0.0000000000001 11 nm A red blood cell
14 0.00000000000001 1 nm The length your nails grow every second
15 0.000000000000001 100 pm An atom. If you need this precision, you probably belong in Lawrence Livermore

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.

Question:

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?

Answer:

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 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.

References

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

FAQ: Zmanim and Leap Seconds

Leap Second

Questions:

Answers:

  • Yes
  • Yes, but infinitesimally

Before delving into the answer, I would like to note that zmanim accuracy / precision down to the second that are supported by the API are really nonsense, because variations in refraction make this accuracy pointless. The second (or millisecond) zmanim accuracy / precision subject will hopefully have its own article in the future.
Since 1972, 27 leap seconds have been added to UTC time VS International Atomic Time (TAI). This is in addition to the initial 10 seconds added in 1972 to reflect pre-1972 corrections. The reason for adding leap seconds is to correct our clocks for incorrect original estimates of the speed of earth’s rotation. Assuming that you keep your clock time correct (and add the leap seconds), no change in any zmanim calculations by either the KosherJava zmanim library, or any other zmanim programs or APIs are needed. However, if you have a very accurate clock, and did not change it since 1972, your zmanim calculations will be off by 37 seconds. This is not something any zmanim APIs, apps or programs should have to deal with. Had we added any corrections for leap seconds, your zmanim calculations would be inaccurate.
As far as the Tōhoku earthquake in Japan, this is really the same question as the first question. Yes, that earthquake slowed down earth’s rotation by 1.8 microseconds or 1.8 millionth of a second (meaningless for zmanim). This as well as the impact of other earthquakes that impact earth’s rotation are factored into the leap second calculations that “correct” the time of our clocks and ensure that your zmanim are correct.

Technical Details

The leap second corrections address incorrect clock time that result from a slower earth rotation than expected. To get a drop more technical (thank you Pinny Markowitz), when the rate or the angle of rotation changes (due to earthquakes or other natural or man-made changes such as building of the Three Gorges Dam), the changes are minuscule. These small changes as well as the original incorrect calculation of the length of the day add up over time. On occasion (about every 2 years) the accumulated difference is significant enough to warrant introducing (or theoretically removing, something that has yet to happen) a leap second to reconcile our clocks with the natural one. On any given day, UTC time always considers 86,400 (60 * 60 * 24) seconds as a day. On the day with a leap second, UTC time still considers the day as having only 86,400 seconds, but a second is added to account for each of the seconds over a year or more being a drop too short. There are various ways of making system clocks conform with the UTC standard, but the net effect is always the same, an extra second is added. UTC doesn’t view a second the same way that the atomic clocks (International Atomic Time) do. UTC views a second as 1/86,400 of a relative day (that is actually 86,400.002 seconds long on average), while, atomic clocks count a day as 86,400 fixed length seconds. Fortunately, the approach of adding leap seconds is exactly what we need when calculating zmanim. By ignoring leap second events in zmanim code, and instead focusing on the measurements of a relative day, we can yield calculations that will be correct in the context of a relative day (assuming that you properly adjust your clock).

FAQ: Different Parshas Hashavua in Eretz Yisrael Than Chutz La’aretz

KosherJava Zmanim API FAQ

Question:

Why does the KosherJava Zmanim API seem to sometimes return the incorrect parshas hashavua in Israel?

Answer:

I have had a number of inquiries this year about the incorrect Parshas Hashavua being returned by the API. In all cases this has been a complaint for Eretz Yisrael and not Chutz La’aretz. The explanation is pretty simple and covered in the API documentation for the JewishCalendar class, but may not be clear to all. When the first day of Pesach occurs on a Shabbos, as it did this year (5775), the last day of Pesach in Eretz Yisrael is on a Friday. The following day is a regular Shabbos in Eretz Yisrael with the usual krias hatorah, but in chutz la’aretz it is the 8th day of Pesach, resulting in krias Hatorah for Pesach. The following weeks will have different krias HaTorah in Eretz Yisrael vs chutz la’aretz, and this will continue for a number of weeks until a double parsha in chutz laaretz is added to equalize the parsha. This last occurred in 2012 (before the release of the calendar functionality in the Zmanim 1.3 release) and will occur again next year. If you are coding to display the Parshas Hashavuah for use in Israel, it is important to set the inIsrael(true) flag (it has a default of false).

JewishDate.setInIsrael(true);

A fuller example showing how to set the indicator and showing the comparison of Eretz Yisrael and Chutz Laaretz this year can be seen in this example.

JewishCalendar israelCalendar = new JewishCalendar(5775, JewishDate.NISSAN, 7);
israelCalendar.setInIsrael(true); //set the calendar to Israel
JewishCalendar chutsLaaretzCalendar = new JewishCalendar(5775, JewishDate.NISSAN, 7);
chutsLaaretzCalendar.setInIsrael(false); //not really needed since the API defaults to false
HebrewDateFormatter hdf = new HebrewDateFormatter();
System.out.println("Date\tChutz Laaretz / Eretz Yisrael"));
for(int i = 0; i < 57; i++){
	israelCalendar.forward(); //roll the date forward a day
	chutsLaaretzCalendar.forward(); //roll the date forward a day
	if(chutsLaaretzCalendar.getDayOfWeek() == 7){ //ignore weekdays
		System.out.println(hdf.formatParsha(chutsLaaretzCalendar) + "\t" + hdf.formatParsha(israelCalendar) + " \\ " + hdf.format(chutsLaaretzCalendar));
	}
}

the output of this is

Date               Chutz Laaretz / Eretz Yisrael
8 Nissan, 5775     Tzav / Tzav
15 Nissan, 5775     / 
22 Nissan, 5775     / Shmini
29 Nissan, 5775    Shmini / Tazria Metzora
6 Iyar, 5775       Tazria Metzora / Achrei Mos Kedoshim
13 Iyar, 5775      Achrei Mos Kedoshim / Emor
20 Iyar, 5775      Emor / Behar
27 Iyar, 5775      Behar Bechukosai / Bechukosai
5 Sivan, 5775      Bamidbar / Bamidbar

It should be noted that this discrepancy is not rare and happens about 25% of the calendar years.