FAQ: How do I Calculate the Jewish/Hebrew Date for …?

Sunrise Calendar

This FAQ is now obsolete. Jewish Calendar Calculations are now supported. See the Zmanim API 1.3.0 Release announcement

Question:

How do I get the Jewish Date for … using the Zmanim API?

Answer:

The current version of the Zanim API does not support Jewish calendrical calculations. Zmanim are almost exclusively based on the solar calendar, so for example, the sunrise on February 8th this year in Montreal (or any other date and location), will be almost the same every year. for this reason there was little point (as far as zmanim) to support Jewish date calculations in the API. One of the only zmanim to rely on a Jewish date is the sof zman kidush levanah calculation, though there are some opinions that it is purely molad based, and this can be calculated without a Jewish calendar component to the API. This zman is obviously not currently implemented in the Zmanim API. I am currently working on adding Jewish date support to the API. The code is based off Avrom Finkelstein‘s no longer active HebrewDate project. I refactored a lot of the code and fixed a number of bugs. Anyone interested in alpha testing this code can download the latest Zmanim SVN code.
I mentioned that it “will be almost the same every year” and this is due the the approximate 1/4 day drift between the 356 day calendar year and the approximately 365.25 days actually present in the astronomical year, a discrepancy corrected every leap year. A future FAQ (probably a few of them) may delve specifically into this drift as well as general zmanim accuracy issues in detail.
If you are simply looking to convert a Hebrew date to Gregorian or Gregorian to Hebrew online without the API, try the JewishGen calendar conversion tools.

FAQ: Why Some Zmanim Never Occur (Developers Beware)

Question:

Why do Some Zmanim Never Occur in Some Locations? (Developers Beware)

Answer:

While most people realize that the sun may not rise or set in the Arctic and Antarctic Circles (see the Star-K’s When Does One Pray When There Is No Day), many are not aware that some twilight dips will not occur during part of the year as far south of the Arctic Circle as London. For example around the summer solstice in London (on the zmanim map) the sun will never dip far enough below the horizon to reach Alos 16°. This happens in London from June 5th till July 8th. The image seen on the top right (original at timeanddate.com) shows various civil twilights centered on London on Midnight June 21st. Look carefully to see the various bands of twilight. Gateshead will not have Alos 16° from May 16th through July 28th, while Anchorage, Alaska (yes there is a Frum Shul in Anchorage with an interesting davening direction issue that is discussed in the Davening Direction from Alaska post ) will not have Alos 16.1° from April 25th to August 20th. Zmanim based on sunrise such as Also 72 that is a 72 minute offset of sunrise can be calculated as long as sunrise can be calculated, something that will happen as long as you are not in the Arctic or Antarctic Circles.
For this reason, the Zmanim API will return a null when a zman will not happen. A Long.MIN_VALUE will be returned when a long is expected such as in the case of a Shaah Zmanis. While an inconvenience to developers who have to code for this, the alternative of a default date would mean that developers unaware of this would return incorrect zmanim, something far worse than a program error from a NullPointerException.
In recent weeks two publicly available programs using the Zmanim API ran into issues due to nulls returned for early alos times. Being something not anticipated by the developers, the nulls generated errors in the programs that quickly led to fixes. For this reason Yitzchok updated the Zmanim .NET project to return the nullable DateTime? instead of the regular DateTime that it had previously been returning. While the Zmanim API documentation always made the possibility of a null being returned possible, I modified the documentation to make this clear on the return value documentation for every zman. Code with the modified documentation was part of the recently released Zmanim API 1.2.1.

FAQ: How Much Earlier is Sunrise on Mount Everest Due to Elevation?

Sunrise over Everest

Question:

How Much Earlier is Sunrise on Mount Everest Due to Elevation?

Answer:

The greatest sunrise and sunset elevation effect on Earth is on Mount Everest (at 27.988056 N, 86.925278 E as seen on the Direction to Yerushalayim Map). With an elevation of 8,848 Meters (29, 029 feet), sunrise would be up to 15 minutes and 31 seconds earlier on Mount Everest than on sea level. The range of the effect is from 15 minutes and 31 seconds on June 22nd, to a “low” of 13 minutes 41 seconds earlier on March 18th. Being in a large mountain range with obstructed horizons, it is likely never actually seen that early. In addition to questions about mountains, every few months I get asked about how much earlier sunrise/set can be seen in skyscrapers. There are various halacha questions as to whether this actually affects zmanim that I will mention later. Here are some raw numbers. Burj KhalifaBurj Khalifa (at 25.197222 N, 55.274056 E as seen on the Direction to Yerushalayim Map) is the tallest building in the world. With a height of 828 m (2,717 ft), visible sunrise to someone standing on top of the crown (something unrealistic) on June 22nd would be at 5:24:56 AM versus 5:29:31 AM on sea level, a difference of 4 minutes and 35 seconds. Sunset would be 7:16:35 PM versus 7:12:00 PM at sea level, a difference of 4 minutes and 35 seconds. A more realistic scenario would be the visibility sunrise on the highest floor (the 160th) , an elevation of 672 m at 5:25:23 AM, a difference of 4 minutes and 8 seconds earlier than sea level. Sunset on the 160th floor would be 7:16:08 PM, or 4 minutes and 8 seconds later than at sea level.
As far as the halacha being affected by the elevation of buildings, the Baal Hatanya seems to indicate that tall buildings would make sunset later. See Yisroel vehazmanim ישראל והזמנים Vol II, page 910. In the Shraga Lachaim שרגא לחיים footnotes Rabbi Harfenes states that

ויש להוסיף שהוא דבר תמוה לומר דעד שלא נבנו הבנינים הגבוהים היה זמן שבת התלוי בשקעה”ח (שקיעה ראשונה להגאנים ושקיעה שניה לר”ת) מוקדם, ולאחר שנבנו יש לאחר הזמנים, ועד עכשיו שהיו בניו יארק הבנינים התאומויות (טווין-טאוע”ר בלע”ז) שכל א’ מהם היה בת ק”י קומות היה זמן השקיעה מאוחר, ועתה לאחר שהפילו והרסו אותם רשעים וזדים ארורים ימ”ש חזר הדבר לקדמותו להקדים זמן השקיעה.

FAQ: Where is the Zmanim API Main Method?

KosherJava Zmanim API FAQ

Question:

Where is the main method?

Answer:

This is a more technical variant of the “How do I install the Zmanim API Program?”, but coming from someone who already knows that it is a Java program that can’t be installed, but assumes that it can be run. The main method is the entry point to a Java program. Since this is a library/API and not a program, it does not have a main method. The code to generate zmanim is spelled out in the How to Use the Zmanim API page. Below is a full example of a very simple zmanim program that outputs sunrise, sof zman krias shema and sunset for the current day in Lakewood, NJ. Please ensure that the Zmanim jar (download) is in your classpath.

/**
 * This program is a simple demonstration of the kosherjava.com Zmanim API.
 * To compile, ensure that the Zmanim Jar is in your classpath.
 */
import net.sourceforge.zmanim.*;
import net.sourceforge.zmanim.util.*;
import java.util.TimeZone;
public class SimpleZmanim{
	public static void main(String [] args) {
		String locationName = "Lakewood, NJ";
		double latitude = 40.096; //latitude of Lakewood, NJ
		double longitude = -74.222; //longitude of Lakewood, NJ
		double elevation = 0; //optional elevation
		//use a Valid Olson Database timezone listed in java.util.TimeZone.getAvailableIDs()
		TimeZone timeZone = TimeZone.getTimeZone("America/New_York");
		//create the location object
		GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, timeZone);
		//create the ZmanimCalendar
		ZmanimCalendar zc = new ZmanimCalendar(location);
		//optionally set the internal calendar. If not set it will default to the current date
		//zc.getCalendar().set(1969, Calendar.FEBRUARY, 8);
		System.out.println("Today's Zmanim for " + locationName);
		System.out.println("Sunrise: " + zc.getSunrise()); //output sunrise
		System.out.println("Sof Zman Shema GRA: " + zc.getSofZmanShmaGRA()); //output Sof Zman Shema GRA
		System.out.println("Sunset: " + zc.getSunset()); //output sunset
	}
}

The following would compile and execute this code (sample from a DOS prompt in Windows).

C:\path\to\code>javac SimpleZmanim.java

C:\path\to\code>java SimpleZmanim

Today's Zmanim for Lakewood, NJ
Sunrise: Thu Nov 05 06:30:27 EST 2009
Sof Zman Shema GRA: Thu Nov 05 09:05:21 EST 2009
Sunset: Thu Nov 05 16:50:02 EST 2009

Please see the Zmanim API documentation for a more complete view of the API.

FAQ: How do I install the Zmanim API Program?

KosherJava Zmanim API FAQ

Question:

How do I install the Zmanim API Program?

Answer:

The Zmanim API is not a program that can be installed, but a Java programming library often referred to as an API (Application Programming Interface). This is a building block to be used by programmers who want to easily include zmanim in their own programs. The Zmanim API allows them to do this with minimal understanding of the way zmanim are calculated. A sample of a program that uses the Zmanim API library is the Zmanim Calendar Generator. The Zmanim Calendar Generator collects user entered location information on the web page and submits this to a small Java program that calculates a year’s worth of zmanim and outputs it as an Excel spreadsheet (using the Apache POI library). A future FAQ may provide a list of current programs that use the Zmanim API.