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 com.kosherjava.zmanim.*;
import com.kosherjava.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.

54 thoughts on “How to Use the Zmanim API”

  1. I was wondering if there’s a way to install the zmanim calculator on my Nokia 3100 (J2me equipped). i tried the .jar file but it won’t work. I’m totally naive about these things, but maybe you can help me out?
    thanks

    Reply

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

    Reply

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

    Reply

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

    Reply

  9. Michael,
    At the suggestion of Dr. Irv Bromberg I started the process of modifying a visual clock that shows zmanim. It is very rough at this point, but can be seen at the alpha quality Zmanim Clock page. There are many clocks cluttering this test page, all using slightly different configurations. Clicking on the clock will bring up an actual list of zmanim. I will see if I can find time to update the code.

    Reply

    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);
      Reply

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

    Reply

  14. 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);

    Reply

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

    Reply

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

    Reply

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

    Reply

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

    Reply

    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.

      Reply

        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.

          Reply

    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
ויקהל פקודי
      Reply

      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.

        Reply

    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?

      Reply

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

    Reply

  30. Hello,
    I’m trying the following data:

                string locationName = "Jerusalem, Israel";
            double latitude = 31.788; 
            double longitude = -35.218; 
            double elevation = 800; //optional elevation

    I’m execute the following command:

                GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, timeZone);
            ComplexZmanimCalendar calendar = new                         ComplexZmanimCalendar(DateTime.Now, location)
            {
                AstronomicalCalculator = new SunTimesCalculator()
            };

            var sunrise = calendar.GetSunrise();
            var sunset = calendar.GetSunset();

            Console.WriteLine(sunrise.ToString());
            Console.WriteLine(sunset.ToString());

    And I am getting the following values:

    07/05/20 10:16:06
07/06/20 00:34:49

    WHAT I’M MISSING???

    Reply

  31. Hi KosherJava,

    Thanks for a really great library for zmanim.

    Can you refer me to documentation (or provide yourself) sone insight to the differences of the NOAA and USNO algorithms pertaining to hallacha? I see you went by default with the NOAA algorithm, why?

    Thank you for any insight you an give me.
    Sruly

    Reply

    1. Sruly,
      The USNO algorithm was used by many poskim over the years. It does not differentiate between leap and non-leap years. It is now a drop out of date and is not considered as accurate. Changes to earth’s rotation since the time they were published and other factors contribute to this. Since they do not differentiate between leap and non-leap years, this alone can mean that the data is a day off (something that corrects itself every 4 years). The USNO website has been down for a while, so I am quoting from memory here, but if I recall correctly it was also designed to be accurate from about the year 1980 to 2050 with lower accuracy at the edges. It was never considered more accurate than one minute. You can contrast that with the NOAA algorithm that is based on newer algorithms by Jean Meeus that are considered more accurate. That said, you will find very small differences between the two. See the old post Zmanim Bug Report from the Land of the Midnight Sun that references the two. You can see the extract on a study comparing them to have an idea.
      Please feel free to ask for additional clarification.
      That said, none are really accurate due to atmospheric conditions. See The Novaya Zemlya Effect’s Impact on Zmanim article that covers this.

      Reply

  33. hi dear tzadikim
    i saw your work and it is amazing
    what i want to know is why it is called api if there is no way (that i noticed) to call it but a series of methids that return data

    does it mean that i have to create a controller that does it?

    thanks again
    chen, israel

    Reply

Leave a Reply

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