How to Use the Zmanim API

First ensure that the Zmanim jar (download) is in your classpath
Import the package and create an instance of either the AstronomicalCalendar, ZmanimCalendar or ComplexZmanimCalendar.

String locationName = "Lakewood, NJ";
double latitude = 40.096; //Lakewood, NJ
double longitude = -74.222; //Lakewood, NJ
double elevation = 0; //optional elevation
TimeZone timeZone = TimeZone.getTimeZone("America/New_York");
GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, timeZone);
ComplexZmanimCalendar czc = new ComplexZmanimCalendar(location);

Note: The TimeZone has to be a valid timezone listed in the java.util.TimeZone.getAvailableIDs().
Note: For locations such as Israel where the beginning and end of dailight savings time can fluctuate from year to year, create a SimpleTimeZone with the known start and end of DST.

To generate zmanim, invoke:

Date sunrise = czc.getSunrise();
Date alos16 = czc.getAlos16point1Degrees();

The date that zmanim are generated for are stored in the Calendar object within the ZmanimCalendar. By default it is the date that the ZmanimCalendar was created. It can easily be reset in many ways.

czc.getCalendar().set(1969, Calendar.FEBRUARY, 8);

or

czc.setCalendar(new GregorianCalendar(1969, Calendar.FEBRUARY, 8));

when generating zmanim for a range of dates, the date can be rolled forward

czc.getCalendar().roll(Calendar.DAY_OF_YEAR, 1);

The real power of this API is the ease in calculating zmanim that are not part of the API. The mothods for doing zmanim calculations not present in the ComplexZmanimCalendar or it’s superclass the ZmanimCalendar are contained in the AstronomicalCalendar, the base class of the calendars in our API since they are generic methods for calculating time based on degrees or time before or after sunrise and sunset and are of interest for calculation beyond zmanim calculations. Here are some examples:
To get alos calculated as 14º below the horizon (as calculated in the calendars published in Montreal) add AstronomicalCalendar.GEOMETRIC_ZENITH (90º) to the 14º offset (measurements are from the vertical, so sunrise and sunset are 90º below the vertical):

Date alos14 = czc.getSunriseOffsetByDegrees(AstronomicalCalendar.GEOMETRIC_ZENITH + 14);

To get the time of mincha gedola calculated based on the MGA using a shaah zmanis based on the day starting 16.1º below the horizon (and ending 16.1º after sunset) the following calculation can be used:

Date minchaGedola = czc.getTimeOffset(czc.getAlos16point1Degrees(), czc.getShaahZmanis16Point1Degrees() * 6.5);

A slightly more complex example would be calculating plag hamincha based on a shaah zmanis that is not present in this API. While a drop more complex it is still rather easy. For example if you wanted to calculate plag based on the day starting 12º before sunrise and ending 12º after sunset as calculated in the calendars in Manchester, England (there is nothing that would prevent your calculating the day using sunrise and sunset offsets that are not identical degrees, but this would lead to chatzos being a time other than the solar transit (solar midday)). The steps involved would be to first calculate the shaah zmanis and than use that time in milliseconds to calculate 10.75 hours after sunrise starting at 12º before sunset

long shaahZmanis = czc.getSolarHour(czc.getSunriseOffsetByDegrees(AstronomicalCalendar.GEOMETRIC_ZENITH + 12), czc.getSunriseOffsetByDegrees(AstronomicalCalendar.GEOMETRIC_ZENITH + 12));
Date plag = getTimeOffset(czc.getSunriseOffsetByDegrees(AstronomicalCalendar.GEOMETRIC_ZENITH + 12), shaahZmanis * 10.75);

Below is a full example (from the FAQ: Where is the Zmanim API Main Method?) 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
		//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.

43 thoughts on “How to Use the Zmanim API”

  1. Andy,
    At this point there is no way to use this on a J2ME device. For one, J2ME does not support floating point data types (double and float) that is used in the code. There are libraries for this, but it would not work without code changes. Secondly, there is no real front end for the API. the 2 sample output classes generate PDF and Excel documents with zmanim.

  2. I was looking at the code for the zmanim API, and I found that by default, the software uses the SunTimesCalculator class for the implementation of the AstronomicalCalculator. I was wondering if you could comment on why you picked that implementation over the other two classed that are provided.
    Thanks,
    Yossie

  3. There is no .NET implementation yet. I do have a .NET dll that uses J# that was created by AdminJew, but it is not very easy to use since it requires the use of Java within .NET. One complicating factor in porting to .NET is that .NET does not easily support switching timezones. The code should be easy to port otherwise.

    1. Anonymous,
      The base class of the Calendar classes in the Zmanim API, the AstronomicalCalendar has a method getTimeOffset(Date time, double offset) that does exactly what you are looking for. The API uses it internally to calculate times such as the 72 minute zman. Please see the Elevation Now Only Impacts Sunrise and Sunset Calculations in the Zmanim API post to understand why sea level sunrise and sunset should be used. The example below shows how to calculate alos as 72 minute before sunrise, and tzais as 72 minutes after sunset.

      String locationName = "Lakewood, NJ";
      double latitude = 40.096; //Lakewood, NJ
      double longitude = -74.222; //Lakewood, NJ
      double elevation = 0; //optional elevation
      TimeZone timeZone = TimeZone.getTimeZone("America/New_York");
      GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, timeZone);
      //Use any of the API's Calendar classes
      //AstronomicalCalendar zCal = new ComplexZmanimCalendar(location);
      //ZmanimCalendar zCal = new ComplexZmanimCalendar(location);
      ComplexZmanimCalendar zCal = new ComplexZmanimCalendar(location);
      //Return the time 72 minutes before sunrise
      Date alos = zCal.getTimeOffset(getSeaLevelSunrise(), -72 * MINUTE_MILLIS);
      //Return the time 72 minutes after sunset
      Date tzais = zCal.getTimeOffset(getSeaLevelSunset(), 72 * MINUTE_MILLIS);
      
  4. How do I set the daylight saving time for the Israeli version. Net?
    i saw Note: For locations such as Israel where the beginning and end of dailight savings time can fluctuate from year to year, create a SimpleTimeZone with the known start and end of DST.
    and I did not understand it.
    Do you have an example?

  5. Yossi,

    In the .NET port there is a class called OffsetTimeZone which allows you to specify the amount of hours to offset from UTC.

    For more advanced implementations you can implement the ITimeZone interface.

    ITimeZone timeZone = new OffsetTimeZone(3);
    var location = new GeoLocation(locationName, latitude, longitude, elevation, timeZone);
    var zc = new ComplexZmanimCalendar(location);

  6. Hi i followed the above code and imported the JAR in android
    but as soon as i call the GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, timeZone);

    it just crash my app. do you have any help in setting your API to work in android

    all compiles but crashes
    Please help becasuse this API is amazing

    Cheers Steve.

    dont know if you could do a simple project.

  7. hey there guys!first of all very usefull and greate library!thanx a lot. i was wondering if you have a hebrew language support. i mean if i want to display a hebrew date on hebrew language in my application,how could i do that and if can?thanx again,for your time.

  8. Hi,
    I was looking for such an api to produce a printable calendar for our Synagogue. I’ve studied your’s.

    So I would like to congratulate you for this excellent quality code. Functional, clear, for the most “alahikly” correct, What could i add else ?

    Thank you

  9. Hi,
    I was wondering how to use this beautiful tool in HTML?
    I would like to team up with KosherJava to make a nice header for websites with the Hebrew/English dates, Zmanim, and the Daf Yomi (with nice styling, too). Would it be possible for whoever would like to help (including other viewers, not only KosherJava…) at dovyn@weissfamily.ca.
    I think it would really be a big help for KosherJava to have something that everyone can add to their website.
    Thanks so much,
    Dovy Neuman

    1. Dovy,
      As far as HTML, you will have a pretty hard time. The KosherJava Zmanim API is written in Java, and was ported to .NET in the Zmanim .NET project, and Objective C. There is a WordPress Hebrew Date Plugin written in PHP, but it does not include zmanim. Moshe Beshkin published the WordPress Zmanim Widget that uses PHP, but is not a port of this API. Your site uses ASP, so you may be able to use the .NET port.

        1. Anything is possible if you are a programmer, but it will not be simple. The main issue you will have with a JavaScript implementation is the time zone concept (thought there are some libraries that do try to provide a JS implementation if the TZ DB (Olson DB)), and that will be the biggest obstacle to porting it. I have no time to do anything like this at the time. Let me know if you make any progress.

    1. David,
      Can you share the code you are using? In my tests it works as expected. You can also see it working properly by generating a calendar in the Zmanim Calendar.

      HebrewDateFormatter hdf = new HebrewDateFormatter();
      JewishCalendar jd = new JewishCalendar(5775, JewishDate.ADAR, 23);
      System.out.println(hdf.formatParsha(jd));
      hdf.setHebrewFormat(true);
      System.out.println(hdf.formatParsha(jd));
      

      outputs

      Vayakhel Pekudei
      ויקהל פקודי
      
      1. Hello,
        Thank you for replying,
        You right, when you give the date manually the output is correct,
        but if i want to do it automatically by getTime();
        it gives me the last week parasha (כי תשא)

        HebrewDateFormatter hdf = new HebrewDateFormatter();
        JewishCalendar jd = new JewishCalendar();
        jd.getTime();
        System.out.println(hdf.formatParsha(jd));
        hdf.setHebrewFormat(true);
        System.out.println(hdf.formatParsha(jd));
        

        I tried something and if i add +1 to
        the index in the code like this:

        public String formatParsha(JewishCalendar jewishCalendar) {
            int index = jewishCalendar.getParshaIndex();
            return index == -1 ? "" : hebrewFormat ? hebrewParshiyos[index + 1] : transliteratedParshios[index +1];
        }
        

        The output is ויקהל and manually as you did – תזריע מצורע.

        Why is that?

        Thank you for helping me.

    1. Daniel,
      You are correct. This past Shabbos was not parshas Shemini, but Yom Tov, and a parsha index of -1 is returned resulting in no parsha output. Displaying Shemini would be incorrect. Returning the exact chol hamoed kriah is not currently supported by the API.
      Out of curiosity, how are you using the API?

  10. In the code for JewishDate I noticed that the Jewish epoch is a negative number. While that makes sense – the epoch was before 1/1/1ad – when calculating a Jewish date from the absdate the calculation is absdate + epoch which yields a negative number which is then divided by 366 to give the approximate Jewish year – however since the epoch was negative the approximate year is in the negative 1700 range. The code then goes on adding years one by one to get to the Jewish year – or approximately 7500 unnecessary calculations (which can quickly add up)

    Easily fixed by changing the epoch to a positive number or doing a conversion to a positive number in the Jewishdate from abs function

    Sorry for giving a bug report in the comments section – I couldn’t find another way to send it

Leave a Reply

Your email address will not be published. Required fields are marked *