Skip to main content

Specifying a location for Jewish calendar APIs

Posted on by

Hebcal.com Web APIs allow the developer to specify a location using one of four options.

Location is used to estimate candle-lighting, Havdalah, fast start/end times, and other zmanim (halachic times). All of these times are derived from a solar position calculation, which are approximated from a location (latitude, longitude) and day of year.

Option 1: GeoNames

To specify a location using a GeoNames numeric ID, use the geonameid parameter, e.g. geonameid=3448439

The GeoNames geographical database covers all countries and contains over eleven million placenames that are available for download free of charge. Hebcal.com supports a subset of the full database: approximately 150,000 world cities with a population of 1,000 or more.

For a complete list of IDs that the Hebcal.com web APIs accept, download the cities1000.zip from https://download.geonames.org/export/dump/ and consider only rows with a type of P (inhabited place). Hebcal refreshes this database approximately once per year.

Option 2: United States ZIP code

To specify a location using a 5-digit ZIP code in the US, use the zip parameter, e.g. zip=90210

If a longer ZIP code (for example a ZIP+4) is specified, only the first 5 digits will be considered.

Hebcal licenses a commercial ZIP code database and we refresh this database approximately once per year.

Option 3: Latitude and Longitude

To specify a location using a latitude and longitude and timezone, use 3 required parameters and one optional parameter.

  1. latitude=[-90.0 to 90.0] – latitude in decimal format (e.g. 31.76904 or -23.5475)
  2. longitude=[-180.0 to 180.0] – longitude decimal format (e.g. 35.21633 or -46.63611)
  3. tzid=TimezoneIdentifier. See List of tz database time zones

Be sure to use the “TZ database name” such as America/New_York or Europe/Paris, not a UTC offset.

An optional parameter elev=[1-9000] may also be used to specify the elevation in meters. This parameter will be ignored unless ue=on, see below for further details.

Option 4: Legacy city identifier (deprecated)

To specify a location using one of ~400 Hebcal legacy city identifiers, use the city parameter, e.g. city=GB-London

You must use one of the legacy city identifiers. Case insensitive. This approach is generally deprecated, as we now recommend using geonameid instead.

Elevation

All of the above options can optionally utilize an elevation for sunset calculation. To enable elevation, specify ue=on (default off).

If on, use elevation to affect the calculation of all sunrise/sunset based zmanim. Note: there are some zmanim such as degree-based zmanim that are driven by the amount of light in the sky and are not impacted by elevation. These zmanim intentionally do not support elevation adjustment

Accuracy

For more information on the calculation engine, see How accurate are candle lighting times?

Yahrzeit calendar search

Posted on by

Hebcal’s Yahrzeit + Anniversary calendar lets you create a personal list of Yahrzeit (memorial) and Yizkor dates, Hebrew Birthdays and Anniversaries for 20+ years. Once your personal list has been created, you can subscribe to free annual email reminders & calendar downloads to Apple, Google, Outlook, and more.

To keep things simple, Hebcal does not require any user registration or login. After creating your calendar, you may optionally sign up to receive annual reminder emails (sent one week before and one day before each anniversary).

If you have signed up for annual email reminders and would like to view or make changes to an existing calendar, the easiest way to find your calendar is by searching for an existing Yahrzeit + Anniversary Calendar by email address. If your email address is found, a confirmation email message will be sent to your email address containing personal calendar link(s). Click the link(s) within that message to view your personal calendars.

Yizkor Memorial Prayer

Posted on by

Yizkor (Hebrew: יִזְכּוֹר) is an Ashkenazi Jewish memorial prayer service for the dead. Yizkor is recited in synagogue as part of the service during four holidays each year:

  1. Yom Kippur
  2. Shmini Atzeret
  3. The final day of Passover (8th day Pesach in Diaspora, 7th day Pesach in Israel)
  4. Shavuot (2nd day Shavuot in Diaspora)

Select the “Include Yizkor dates” option when you create your personal Hebcal Yahrzeit + Anniversary calendar to be reminded of these dates.

Read more about Yikzor from My Jewish Learning, Chabad, and Wikipedia.

Yahrzeit refers to the anniversary, according to the Hebrew calendar, of the day of death of a loved one.

Tanakh Yomi / תנ״ך יומי

Posted on by

From ancient biblical times, the Torah has been divided into portions which are read each week on a yearly calendar. In line with this tradition, various calendars have emerged to facilitate groups of learners in collectively studying designated texts.

Tanakh Yomi is a daily learning cycle for completing Tanakh annually. On weekdays, 293 chapters of Prophets (Nevi’im) and Writings (Ketuvim) are recited according to the ancient Masoretic division of sedarim. On Shabbat, each Torah portion is recited.

In addition to Shabbat, the Tanakh Yomi calendar also skips major holidays (Pesach days 1 and 7, Shavuot, Rosh Hashana , Yom Kippur, Sukkot day 1, Shmini Atzeret), Purim, Yom HaAtzma’ut, and Tish’a B’Av.

The Tanakh Yomi cycle completes each year and restarts the day after Shmini Atzeret. The cycle follows the Israeli schedule in the sense that it does not make any special accommodations for yom tov sheini. The Hebcal implementation was created after careful study of the schedule posted at דף הבית | תנ״ך יומי website.

You’ll find Tanakh Yomi on our Daily Learning pages and also on the Downloads page.

Changing timezone causes Outlook all-day events to shift

Posted on by

We occasionally receive reports from Outlook on Windows users experiencing a problem with Hebcal calendar events spanning two days. For example, rather than a holiday appearing as an “all-day” event with no particular time, each event appears to be a 24-hour long event that starts at 11pm (23:00) on one day, and end at 11pm on the other day.

The root cause of the problem seems to be when the computer changes time zones. For example, the Hebcal calendar feed was generated for Tel Aviv, but then the computer or Outlook timezone was changed to London, England.

We have been able to reproduce this issue on Windows 11, and the fix involves 3 steps:

  1. Adjusting the computer’s timezone to match the calendar feed timezone
  2. Adjusting Outlook’s timezone to match the calendar feed timezone
  3. Restarting Microsoft Outlook

If you are experiencing this problem, here are a few examples of what settings to look for and adjust: