ZIP Codes and Zmanim – Use With Care

99557 ZIP code - the largest in the USA
The 99557 ZIP code in Alaska – the largest in the USA
There are many zmanim services and apps that use ZIP codes as a location finder for calculating zmanim. While very convenient, there is a potential pitfall in using ZIP codes for geolocation. In general, ZIP code geolocation services will provide the center of the ZIP code and zmanim apps calculate zmanim for that location. The issue arises with large ZIP code areas mostly found in rural areas. Take the following two extreme cases that have very large ZIP code areas. ZIP code 89049 for rural Tonopah, NV, is 195 km (121 mi) from east to west. The eastern boundary of this non-contiguous ZIP code has a longitude of -115.417°, while the western boundary is -117.625°. This means that there are 2.2° of longitude between the eastern and western borders of this ZIP code. The earth rotates 1 degree every 4 minutes, so zmanim at the eastern and western edges of this ZIP code are approximately 8.8 minutes apart. Using the typical center of the ZIP based calculations would mean that zmanim would be about 4.4 minutes different at the edges compared to the center. Moving to something a bit more extreme, is the case of ZIP code 99557 of Aniak, Alaska and its surrounding area. This ZIP code is 415 km (258 mi) from east to west. The longitude of the eastern edge of the ZIP code is -153.032°, and the western edge is -160.783°. Being farther north and therefore having shorter distances between degrees of longitude, this ZIP code stretches across 7.7° of longitude. The zmanim difference from the center to the edges of this ZIP code is 15 and a half minutes (31 minutes across the ZIP). While it is indeed rare to have such large distances, there are 193 US ZIP codes that are over 1° of longitude wide, meaning that the zmanim difference for these ZIP codes are at a minimum 4 minutes apart, or 2 minutes off from the center. There are 1,463 or 4.4% of all ZIP codes with 0.5° or greater distance between east and west (a minimum of a 2 minute zmanim difference between the east and west zide of the ZIP code). zmanim software developers should be aware of this, and take care to alert users of possible inaccuracies when using large ZIP code areas, or require addresses or more specific location information for large zip codes.
Let’s contrast the above with Lakewood, NJ. With 0.107° of longitude from east to west, zmanim are 24 seconds later on the west side (the intersection of New Central Ave & N Hope Chapel Rd) than the east side (Shinn Cranes, 1600 Ocean Ave).
See the Calculation of Zmanim VS Other Sites post for additional related material.
I thank Avraham David Gelbfish for generating the ZIP code longitude range for all 33,093 ZIP codes from the US Census Bureau ZIP code shape files.

Parsha Code Removed from KosherJava Zmanim Calendar API

Java CalendarDue to licensing issues that were brought to my attention last year, the parsha code was removed from the Zmanim API on Aug 22, 2016. In the future I may release the parsha code as a standalone module under the GPL license, or create a new LGPL implementation. To understand this more clearly, the current Zmanim API is licensed under the LGPL, while the parsha code contained some GPL code that had to be removed in order to retain the LGPL license. I would welcome any code submission for parsha code that could be released under the LGPL.

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

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 Pesach kriah. 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 flag (it defaults to 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.

FAQ: Calculating the Baal Hatanya’s Shkiah

Zmanim API FAQ

Question:

How do I calculate the Baal Hatanya’s Zman for Shkiah as 4 minutes after sunset using the KosherJava Zmanim API?

Answer:

I was recently asked how to use the Zmanim API to calculate the Baal Hatanya’s opinion is that shkiah (halachic sunset) is 4 minutes after civil sunset. The assumption that the Baal Hatanya’s shkiah is a fixed 4 minutes after sunset is not that simple and will require a separate post to clarify. This zman should not be used lehalacha without consulting a rov. This post shows how to us the API assuming that it is a fixed 4 minutes after sunset. The technique to calculate this with the API is identical to the way getTzais72() would be calculated. The source of that method is

public Date getTzais72() {
    return getTimeOffset(getSeaLevelSunset(), 72 * MINUTE_MILLIS);
}

The getTimeOffset(Date time, double offset) method in the base class AstronomicalCalendar is very simple:

public Date getTimeOffset(Date time, long offset) {
    if (time == null || offset == Long.MIN_VALUE) {
        return null;
    }
    return new Date(time.getTime() + offset);
}

The getTimeOffset method simply adds the number of milliseconds of the offset to the raw time of the zman and returns it as a date. While using the API itself is not needed for such a simple calculation, here is how it would be used:

String locationName = "Jerusalem";
double latitude = 31.778; // Har habayis
double longitude = 35.2354;// Har Habayis
double elevation = 0;
TimeZone timeZone = TimeZone.getTimeZone("Asia/Jerusalem");
GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, timeZone);
ZmanimCalendar zc = new ZmanimCalendar(location);
Date baalHatanyaShkiah = zc.getTimeOffset(zc.getSeaLevelSunset(), 4 * 60000);
System.out.println("Baal Hatanya Shkiah: " + baalHatanyaShkiah);

Adding it to the API itself would be even simpler:

public Date getShkiahBaalHatanya() {
    return getTimeOffset(getSeaLevelSunset(), 4 * MINUTE_MILLIS);
}

At some point in the future I may (doubtful) add this time to the API itself. The zman is not commonly used, and the Chabad calendars that I have seen all use regular sunset.

Update on ‍‍July 5, 2015 – י״ח תמוז תשע״ה: This article was updated to clarify that the Baal Hatanya’s opinion may not be a fixed 4 minutes, but that the post was showing how to use the API to calculate it based on the questioner’s assumption that it was a 4 minute zman.

Zmanim API 1.3.0 Released

Zmanim API 1.3.0 ReleaseThe Zmanim API version 1.3.0 was released on March 4th, 2013 כ״א אדר תשע״ג. Various changes in the new release VS the previous version 1.2.1 that was released in May 2010 can be seen below. This release includes beta support for Jewish Calendar calculations as well as a number of updated zmanim and refactored code. The Jewish Calendar support in the Zmanim API is based on Avrom Finkelstien’s HebrewDate project released in 2002. Unlike the Zmanim code, the Jewish calendar interfaces may change significantly in the future (see Jay Gindin’s various changes that may make it into this API) and should therefore be considered beta.

Changes in the Zmanim API 1.3.0 release

Changes since March 23, 2011 have been in SVN and detailed changes can be seen there.

KosherJava Zmanim API Powering Many Mobile Apps

Mobile apps using Kosher Java Zmanim APIIn the past I posted about Android Zmanim, Jay Gindin’s open source Android zmanim project that uses the KosherJava Zmanim API. The fact that Android development uses Java natively means that it is very simple for Android developers to include zmanim in their apps. Since that time there have been a number of other applications (including iPhone apps) using the code. Moshe’s KosherCocoa Obj-C port of the KosherJava Zmanim API will probably result in additional iPhone apps that use the API. Yitzchok’s older Zmanim .NET port of the KosherJava Zmanim API also opened the door for Windows Phone zmanim applications as well (Ari Polski’s Zmaim app already uses it, and there are others in the works). I may post additional details about some of them in the future, including an updated post about Jay’s latest Android Zmanim release. I am aware of the following mobile applications that use the KosherJava Zmanim API.

There are also a few secular apps that are non-zmanim specific that use the API for sunrise and sunset calculations. One that I know of is Jeffrey Blattman’s Dawn to Dusk Widget, and I know that there are some photography apps that use it for sunrise/set calculations as well. There are likely more that I have missed, and a few that are in active development but unreleased. If you are aware of any missed apps, please let me know.