# How to Use the Zmanim API

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.

## 50 thoughts on “How to Use the Zmanim API”

1. andy sinton says:

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

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.

3. Yossie Teichman says:

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

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.

5. Raphi says:

Do you have this code in .net by any chance?

6. jack boe says:

Is there a way to incorporate this by using an httprequest from an asp page. Like an xml page, where I would send the variables and get a response with the correct candle lighting time?

thanks

7. Jack,
you seem to be requesting a REST style Web Service. This is very simple using the Zmanim API, since the toString method returns an XML representation of the calendar including any zmanim that you might need. All you need is a Java Servlet that would return data from the API.

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

9. Michael Kopinsky says:

Is there a zmanim Java applet available? I would like something that I can place on my desktop as an Active Desktop item. Such things are available for candlelighting times (for example, see http://www.torahtots.com/timecapsule/cities/philadelphia.htm), but I have not found anything for zmanim, and I don’t have the applet programming skills to make it myself.

Thanks,
Michael

10. shalom
i would like to get the PHP lignes to obtain a block with shabbat parcha and zmanim candles for paris france
i want them please !!! READY to copy and past because i am not prgrammer
see my website http://www.rungiscacher.com

kol tuv

1. Mordekhai,
Moishe Beshkin (see his KosherDev blog) wrote the WordPress Zmanim Widget plugin that does what you are looking for. Since your site does not appear to be a WordPress site, I suggest that you contact him to see if there is a way his code can be used in a non-WordPress PHP page.

11. anonymus says:

Is there a way to calculate times based on minutes, something like getTimeOffsetByMinutes(int minute);

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

12. yossi says:

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?

13. Yitzchok says:

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

14. Steve says:

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

Cheers Steve.

dont know if you could do a simple project.

1. Steve,
I would suggest that you look at the way the code is structured in the Android Zmanim project. I have never used the Zmanim API in an Android application, but they and others have.

15. anton says:

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.

16. Michael M. says:

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

17. Shmuel says:

Can I use this in an app I’m making for Android? The app will be free and I will give credit to you for this awesome framework.

1. Shmuel,
You can certainly use it. The API is open source and free to use.

18. bk says:

day light saving time
how adjuset it to new time of summer clock in israel?

19. Dovy Neuman says:

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 Neuman says:

I don’t use WordPress, and I already have a Hebrew date generator.
I would like to get Zmanim and Daf Yomi inside a nice header.
Also, I have Googled Java to Javascript translators. I found a couple. I was wondering:
1. If it is possible to do that.
2. How to do it.
3. How to use it.

Thanks,
Dovy

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. Dovy Neuman says:

If so, how can I use the .NET API with ASP.NET?
And how do you use the original Java API on your website with your Zmanim Map?
Thanks,
Dovy

1. I am not a .NET developer, so I can’t answer this. As far as the map, it uses a web service that I have no plans on supporting out of my own site at the moment.

20. Dovy Neuman says:

Then how can I contact Yitzchok, the person who ported it, to ask him for help?

21. aharon says:

hello,
I want to display Parshas Hashavua every day of the week (not only on shabbos), what is the best way to do it?

Thanks a lot,

aharon

1. Aharon,
at this point the API does not support it, but the good news is the the underlying code can easily be modified to support it, and it is even mentioned in the getParshaIndex() method in the JewishCalendar class JavaDoc. Have a look at the source and feel free to modify it. At this point I have no plan to make the change to the API itself.

22. David says:

Hello,
I dont know why but this week the parasha is ויקהל-פקודי and the output
is only ויקהל.

Thanks,
David.

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. David says:

Hello,
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.

23. daniel says:

hello,

your code working very well but i dont know

why this week there is no output for parasha?

(maybe because of passover?)

Thanks

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?

24. david says:

Hello,
I am in israel and this week the parasha should be “בהר” and the output is “בהר-בחוקותי”

How do we fix it?

25. Levi says:

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

26. Reuven says:

hi, there is someone can show the source code how to use it on android
the full activity code and how to use the zmanim jar.
thanks

27. Dan890 says:

Hi, thanks for the professional API!

I’m working with “Zmanim Framework for .NET” , i’m sending “Asia/Jerusalem” time zone but the results is wrong -i get utcOffset 2:00 instead utc 3:00

1. Dan,
I do not know .NET. I suggest that you contact Yitzchok who wrote that code. If you can’t find contact info for him, contact me and I will try to track down his email address.

28. Mendel Greenberg says:

I am having a problem with ComplexZmanimCalendar. If I enter a location from a different time zone, it will always return a date set to Eastern Time. Can you help me with this?

29. Shlomi Elbaz says:

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

30. Sruly says:

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

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.