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

Zmanim API FAQ


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


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 live casino online Canada 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).


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)); } } [/java] the output of this is [code] 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 [/code] 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


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


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.

FAQ: Outputting Zmanim for A Different Time Zone With the the Zmanim API

Zmanim API FAQ


Why does the output of zmanim for a different time zone appear incorrect?


One of the common issues encountered by developers using the API is that zmanim generated for a different time zone than the user’s time zone may return output that appears incorrect. For example a user in Lakewood, NJ trying to calculate sunrise for Yerushalayim may attempt to use the following code:

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);
zc.getCalendar().set(2011, Calendar.FEBRUARY, 8);
System.out.println("Sunrise: " + zc.getSunrise());
System.out.println("Sunset: " + zc.getSunset());

While you would expect a sunrise of 6:27:41 AM and sunset of 5:19:19 PM, running this code on a computer anywhere in the Eastern Standard time zone would generate the following time that appears to be 7 hours early:

Sunrise: Mon Feb 07 23:27:41 EST 2011
Sunset: Tue Feb 08 10:19:19 EST 2011

The issue is simple, and the sunrise and sunset returned above are actually accurate. Zmanim are returned by the Zmanim API as a Java Date object that represents a moment in time (stored internally by Java as Unix Time – the number of milliseconds since the January 1, 1970 GMT). Sunrise in Yerushalayim on February 8th actually happens at 11:27:41 PM on February 7th EST. Java is simply outputting the Date as a String formatted to the users default time zone (EST in this example). The user probably intends to output the time in IST – Israel Standard Time (“Asia/Jerusalem” in the Olson database). To do this you have to output the zmanim using a formatter set to use the “Asia/Jerusalem” time zone.

DateFormat zmanimFormat = new SimpleDateFormat("EEE MMM dd HH:mm:ss z yyyy");

System.out.println("sunrise: " + zmanimFormat.format(zc.getSunrise()));
System.out.println("sunset:" + zmanimFormat.format(zc.getSunset()));

will output the expected

sunrise: Tue Feb 08 06:27:41 IST 2011
sunset:Tue Feb 08 17:19:19 IST 2011

Below is the full code example.

import net.sourceforge.zmanim.*;
import net.sourceforge.zmanim.util.*;
import java.util.TimeZone;
public class FormatZmanim{
	public static void main(String [] args) {
		String locationName = "Jerusalem";
		double latitude = 31.778; //latitude of Har habayis
		double longitude = 35.2354; //longitude of Har Habayis
		double elevation = 0; //optional elevation
		//use a Valid Olson Database timezone listed in java.util.TimeZone.getAvailableIDs()
		TimeZone timeZone = TimeZone.getTimeZone("Asia/Jerusalem");
		//create the location object
		GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, timeZone);
		ZmanimCalendar zc = new ZmanimCalendar(location); //create the ZmanimCalendar
		zc.getCalendar().set(2011, Calendar.FEBRUARY, 8); //set the date
		DateFormat zmanimFormat = new SimpleDateFormat("EEE MMM dd HH:mm:ss z yyyy"); //Create the formatter
		zmanimFormat.setTimeZone(location.getTimeZone()); //set the formatter's time zone
		System.out.println("sunrise: " + zmanimFormat.format(zc.getSunrise()));
		System.out.println("sunset:" + zmanimFormat.format(zc.getSunset()));

Zmanim API Ported to Cocoa / Objective-C

Port City JavaMoshe Berman completed the 2.0 release of his port of the KosherJava Zmanim API from Java to a Cocoa API using Objective-C. You can see the work in the KosherCocoa project page. The original work on the port dates back to Moshe’s iPhone Ultimate Omer 2 (iTunes link) app. In that app, he ported the minimum amount of code needed to calculate sunset in order to roll the day of the Omer after sunset. With Moshe’s latest check-in at github, he provided a port of a good portion of the API sticking to the basic design of the KosherJava API. The complexZmanimCalendar still remains to be ported, but the majority of zmanim in common use are in the ported ZmanimCalendar. Moshe’s blog post Introducing KosherCocoa 2.0 has additional details. Additional developer notes can be seen in the KosherCocoa wiki page. This port will be a boon to iOS developers who now have a simple way to include zmanim in their iPhone and iPad apps.
Here is some sample code that outputs zmanim to the console.


#import <Foundation/Foundation.h>
#import "ZmanimCalendar.h"

int main (int argc, const char * argv[]){

    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];

    //  Set up the location
    NSString *locationName = @"Lakewood, NJ";
    double latitude = 40.096; //Lakewood, NJ
    double longitude = -74.222; //Lakewood, NJ
    NSTimeZone *timeZone = [NSTimeZone timeZoneForSecondsFromGMT:-18000];

    //  Initialize the Zmanim Calendar
    GeoLocation *geoLocation = [[GeoLocation alloc] initWithName:locationName andLatitude:latitude andLongitude:longitude andTimeZone:timeZone];
    ZmanimCalendar *zmanimCalendar = [[ZmanimCalendar alloc] initWithLocation:geoLocation];

    //  Create a Formatter for the date information
    NSDateFormatter *formatter = [[NSDateFormatter alloc] init];
    [formatter setTimeZone:timeZone];
    [formatter setDateStyle:NSDateFormatterNoStyle];
    [formatter setTimeStyle:NSDateFormatterMediumStyle];

    NSDate *sunrise = [zmanimCalendar sunrise];
    NSDate *sofZmanShmaMGA = [zmanimCalendar sofZmanShmaMogenAvraham];
    NSDate *sofZmanShmaGRA = [zmanimCalendar sofZmanShmaGra];
    NSDate *sunset = [zmanimCalendar sunset];

    NSLog(@"Today's Zmanim for %@",  [geoLocation locationName]);
    NSLog(@"Sunrise: %@",  [formatter stringFromDate:sunrise]);
    NSLog(@"Sof Zman Shema MGA: %@",  [formatter stringFromDate:sofZmanShmaMGA]);
    NSLog(@"Sof Zman Shema GRA: %@",  [formatter stringFromDate:sofZmanShmaGRA]);
    NSLog(@"Sunset: %@",  [formatter stringFromDate:sunset]);

    [pool drain];
    return 0;

This would output (on February 8th):

Today's Zmanim for Lakewood, NJ
Sunrise: 6:58:43 AM
Sof Zman Shema MGA: 8:59:04 AM
Sof Zman Shema GRA: 9:35:04 AM
Sunset: 5:24:09 PM

Calculating Kiddush Levana Times Using the Zmanim API

Moon Crescent 3 Day LunationCalculating the earliest and latest times for Kiddush Levana has not been part of the KosherJava Zmanim API until now. This is because unlike other zmanim that solely rely on solar calculations that are tied to the Gregorian calendar, times for Kiddush Levanah depend on the Jewish calendar molad (lunar conjunction) computation. With the recent addition of Jewish calendar support to the alpha releases of the KosherJava Zmaim API 1.3, molad calculation was added, allowing for calculation of kidush levana times. Times include the earliest time calculated as 3 and 7 days after the molad. Sof zman kidush levanah includes the Maharil’s opinion that it is calculated as halfway between molad and molad, and the more lenient full 15 days from the molad mentioned by the Mechaber in the Shulchan Aruch. It should be noted that some opinions hold that the Rema who brings down the opinion of the Maharil’s of calculating half way between molad and molad is of the opinion that the Mechaber agrees with him. Also see the Aruch Hashulchan. For additional details on the subject, See Rabbi Dovid Heber’s very detailed writeup in Siman Daled (chapter 4) of Shaarei Zmanim.

Calculating the Molad

Kidush levanah times depend on the time of the molad. The time of the molad announced in shuls on Shabbos Mevarchim is the time of the Molad Emtzai (Average Molad) in Yerushalayim local mean time. This has to be converted to standard time. Standard time uses time zones to unify clock times across a large area. With 360° of longitude around the globe, the world is divided into 24 timezones (one per hour) resulting in timezones that are 15° of longitude each. Har Habayis with a longitude of 35.2354° is 5.2354° away from the 30° longitude line. Multiply the 5.235° by 4 minutes per degree (15° of longitude per hour) to reach 20.94 minutes, or 20 minutes and 56.496 seconds (5.235 * 4 = 20.94). This time is subtracted from the local molad time to arrive at Standard time. Since the time of the molad is at the same instant globally (unlike zmanim such as sunrise that depend on a person’s location), converting this to a user’s local time involves simply calculating the time difference between the time in Yerushalayim and your location. If daylight savings time is in use, this has to be added to the calculation. Java date formatting classes do this calculation on Date objects without forcing the developer to do any calculations.

Calculating the Start and End of Kiddush Levana Times

The JewishCalendar class contains the methods for claculating these zmanim. Calculating Tchilas Zman Kiddush Levana (the earliest time Kiddush Levana can be said) is done by adding 3 days or 7 days to the molad time. Sof Zman Kiddush Levana (the latest time Kiddush Levana can be said) is either the time between molad and molad calculated by adding 14 days, 18 hours, 22 minutes and 1.666 seconds to the molad (half the 29 days, 12 hours, 44 minutes and 1 chelek (3.333 seconds)), or by adding 15 days to the molad.

Using the Zmanim API Calculate Molad Based Times

Here is sample code for calculating various kiddush levana times for anywhere in the world for Shevat 5729 (1969). Since formatting classes requires a timezone for proper formatting, the simple code below assumes that you are looking for the time in your local timezone. If you want the time for a timezone other than the one your computer is in, set the SimpleDateFormat.setTimeZone() to the timezone you wish to display the times for.

int year = 5729;
int month = JewishDate.SHEVAT;
Date tchilas3Days = JewishCalendar.getTchilasZmanKidushLevanah3Days(year, month);
Date tchilas7Days = JewishCalendar.getTchilasZmanKidushLevanah7Days(year, month);
Date sofZmanBetweenMoldos = JewishCalendar.getSofZmanKidushLevanahBetweenMoldos(year, month);
Date sofZmanKidushLevanah15Days = JewishCalendar.getSofZmanKidushLevanah15Days(year, month);
SimpleDateFormat sdf = new SimpleDateFormat("MMM dd, yyyy 'at' HH:mm:ss z");
System.out.println("Tchilas Zman Kiddush Levana 3 Days: " + sdf.format(tchilas3Days));
System.out.println("Tchilas Zman Kiddush Levana 7 Days: " + sdf.format(tchilas7Days));
System.out.println("Sof Zman Kiddush Levana Between Moldos: " + sdf.format(sofZmanBetweenMoldos));
System.out.println("Sof Zman Kiddush Levana 15 Days: " + sdf.format(sofZmanKidushLevanah15Days));

this will output the following in an EST timezone.

Tchilas Zman Kiddush Levana 3 Days: Jan 21, 1969 at 06:06:29 EST
Tchilas Zman Kiddush Levana 7 Days: Jan 25, 1969 at 06:06:29 EST
Sof Zman Kiddush Levana Between Moldos: Feb 02, 1969 at 00:28:31 EST
Sof Zman Kiddush Levana 15 Days: Feb 02, 1969 at 06:06:29 EST

Kiddush Levana Times During Daylight Hours

As you can see, all of these times are at night (After tzais 72 and prior to Alos 72 minutes in Montreal). Many times, these calculations will result in times that are during daylight hours when Kidush Levana can’t be said. When using the API and calculating the time for the tchilas zman kiddush levana and the time is during daylight hours, the earliest time should be tzais the following night. When the calculated time of sof zman kiddush levana is during daylight hours, the time posted should be alos on the previous night. The API may at some point support a method of automatically calculating this.