Plans for a Zmanim API FAQ

KosherJava Zmanim API FAQ
Questions communicated to me via the contact page far exceed the number of comments in the blog. In the hope of clarifying the most common questions related to the Zmanim API and to a lesser degree other parts of this site, I plan on a series of FAQ posts that will hopefully cut down on the number of questions. The list of FAQs may eventually be consolidated into a FAQ page.

Zmanim Calendar Generator Can Now Output Fewer Zmanim

Sunrise CalendarAfter numerous requests, the Zmanim Calendar Generator can now output a less extensive list of zmanim. While the “full” calendar option (the default) generates an Excel spreadsheet with 108 columns of zmanim, the “standard” output generates a spreadsheet with 15 columns containing the most commonly used zmanim. The exact list of what constitutes commonly used zmanim is likely to be tweaked over time. The spreadsheet was initially designed for developers as a sample of the various zmanim available in the API . Developers can compare the output of their zmanim using the API, or a ported version of the API to the spreadsheet for accuracy. Based on feedback, many people use it to generate shul calendars, and wanted a less daunting list of zmanim.

Zmanim API 1.1 Released


The Zmanim API 1.1 was released early this morning. Information about what changed in this release can be seen in previous posts about various beta and patch releases. A last minute change involved the removal of the misheyakir calculations commonly used by the Syrian community. The removal was due to the various different minhagim used, and Chacham Yosef Harari-Raful not endorsing any one, or including any, in his calendar. The API is flexible enough to be used for any calculation wanted by the various Syrian shuls even without “native” support for a built in “Ateret Torah” misheyakir. Some missing JavaDocs were also added.

I would like to again thank Rabbi Rachamim Ashkenazi the publisher of a zmanim calendar for the Syrian Community, and Victor Grazi for his input, testing and technical expertise used for adding the new “Ateret Torah” zmanim.

The main download is the Zmanim 1.1 release zip file that includes source files and JavaDoc documentation. Also available for download (included in the above zip file) is the main zmanim-1.1.jar and the new zmanimAstronomical-1.1.jar that only includes the AstronomicalCalendar and supporting classes. Additional detail on the downloads can be seen on the Zmanim Download page.

Zmanim Via Instant Messaging Bot

As hinted at in my previous post , there is a new project underway that uses the Zmanim API in a way that I had never really imagined. Using the Smack API, Michael Kopinsky created the ZmanimBot that allows getting zmanim by instant messaging the ZmanimBot, an internet bot. It currently supports the Google Talk IM system, but support for other systems might follow. Please be aware that the system is under development and is not always up. Additional information can be found on the ZmanimBot page.

Update (April 13, 2008): The ZmanimBot is now available via AIM

Updated Zmanim Jar Released – Please Download the Latest


In December when developing the Zmanim / Bearing to Yerushalayim map (blog post), I noticed a problem with the code used to generate zmanim. The API returns a Java Date object. Usually only the time is of interest, and the date is ignored, but in some cases (when a timezone offset is specified without using the Olson DB name (such as America/New_York) or if the GMT timezone is used for other locations, and the local standard time is calculated as an offset of GMT), the date of the sunset returned was earlier than the sunrise date. This caused zmanim such as sof zman Shema for some locations to be incorrect, since the math used was comparing surnise to a sunset on the incorrect date, causing some very odd behavior. Updated files that correct this issue were uploaded to the site on Dec 26th. I was notified today by a developer using the jar, that not all the download links were pointing to the updated versions, and this caused issues for his program (a post about his project will be posted in the near future). All the links have now been updated. Since the old code can sometimes generate incorrect zmanim, it is highly suggested that you replace your current jar with the latest version of zmanim.jar (or zmanim.zip).

Along with the fix mentioned above, a number of other small fixes were done. These include among other minor issues, fixed, better and simplified XML output from the toString method, better error handling for expected error conditions, that had previously caused errors in the generations of zmanim for areas in the arctic circle such as Thule, Greenland. In case you are curious, someone did actually try this, and the error logs lead me to find the issue. The IP address used for the request mapped back to the Thule Air Base.