Skip to main content

Yahrzeit + Anniversary API

We are pleased to offer experimental support for a yahrzeit API.

Clients should POST x-www-form-urlencoded data to https://www.hebcal.com/yahrzeit

The following parameters must be specified

  • cfg=json
  • v=yahrzeit

The following parameters may be specified once

  • years=3 – default 20
  • hebdate=on – append Hebrew date to the event titles (default off)
  • yizkor=on – Include Yizkor dates (Pesach 8th day, Shavuot 2nd day, Yom Kippur and Shmini Atzeret — default off)

Then, specify at least one input date based on the Gregorian date of death (or birth). The following parameters are required, substituting the X with increasing integers beginning with 1.

  • yX=1983 – Gregorian year, 4-digit date
  • mX=4 – Gregorian month, 1 or 2 digits (1=January, 12=December)
  • dX=15 – Gregorian day of month (1-31)
  • sX=on – Event occurred on Gregorian date after sunset (default off implies that event occurred before sunset)
  • tX=Yahrzeit – type (either Yahrzeit, Birthday or Anniversary)
  • nX=Plonit%20ben%20Ploni – name (optional)

Here is an example of two events, a Hebrew Birthday for Example1 and a Yahrzeit for Example2:

curl \
  --compressed \
  -H 'content-type: application/x-www-form-urlencoded' \
  --data-raw 'cfg=json&v=yahrzeit&n1=Example1&t1=Birthday&d1=15&m1=4&y1=1983&s1=on&n2=Example2&t2=Yahrzeit&d2=13&m2=11&y2=2008&s2=off&hebdate=on&years=3' \
  'https://www.hebcal.com/yahrzeit'

The response will be text/json that looks like this:

{
   "title": "Hebrew Anniversaries: Example1, Example2",
   "date": "2021-05-12T17:52:44.991Z",
   "items": [
     {
       "title": "Example2's 12th Yahrzeit (15th of Cheshvan)",
       "date": "2020-11-02",
       "memo": "Hebcal joins you in remembering Example2, whose 12th Yahrzeit occurs on Monday, November 2, corresponding to the 15th of Cheshvan, 5781.\n\nExample2's Yahrzeit begins at sundown on Sunday, November 1 and continues until sundown on the day of observance. It is customary to light a memorial candle at sundown as the Yahrzeit begins.\n\nMay your loved one's soul be bound up in the bond of eternal life and may their memory serve as a continued source of inspiration and comfort to you."
     },
     {
       "title": "Example1's 38th Hebrew Birthday (3rd of Iyyar)",
       "date": "2021-04-15",
       "memo": "Hebcal joins you in honoring Example1, whose 38th Hebrew Birthday occurs on Thursday, April 15, corresponding to the 3rd of Iyyar, 5781.\n\nExample1's Hebrew Birthday begins at sundown on Wednesday, April 14 and continues until sundown on the day of observance."
     },
     {
       "title": "Example2's 13th Yahrzeit (15th of Cheshvan)",
       "date": "2021-10-21",
       "memo": "Hebcal joins you in remembering Example2, whose 13th Yahrzeit occurs on Thursday, October 21, corresponding to the 15th of Cheshvan, 5782.\n\nExample2's Yahrzeit begins at sundown on Wednesday, October 20 and continues until sundown on the day of observance. It is customary to light a memorial candle at sundown as the Yahrzeit begins.\n\nMay your loved one's soul be bound up in the bond of eternal life and may their memory serve as a continued source of inspiration and comfort to you."
     },
     {
       "title": "Example1's 39th Hebrew Birthday (3rd of Iyyar)",
       "date": "2022-05-04",
       "memo": "Hebcal joins you in honoring Example1, whose 39th Hebrew Birthday occurs on Wednesday, May 4, corresponding to the 3rd of Iyyar, 5782.\n\nExample1's Hebrew Birthday begins at sundown on Tuesday, May 3 and continues until sundown on the day of observance."
     },
     {
       "title": "Example2's 14th Yahrzeit (15th of Cheshvan)",
       "date": "2022-11-09",
       "memo": "Hebcal joins you in remembering Example2, whose 14th Yahrzeit occurs on Wednesday, November 9, corresponding to the 15th of Cheshvan, 5783.\n\nExample2's Yahrzeit begins at sundown on Tuesday, November 8 and continues until sundown on the day of observance. It is customary to light a memorial candle at sundown as the Yahrzeit begins.\n\nMay your loved one's soul be bound up in the bond of eternal life and may their memory serve as a continued source of inspiration and comfort to you."
     },
     {
       "title": "Example1's 40th Hebrew Birthday (3rd of Iyyar)",
       "date": "2023-04-24",
       "memo": "Hebcal joins you in honoring Example1, whose 40th Hebrew Birthday occurs on Monday, April 24, corresponding to the 3rd of Iyyar, 5783.\n\nExample1's Hebrew Birthday begins at sundown on Sunday, April 23 and continues until sundown on the day of observance."
     },
     {
       "title": "Example2's 15th Yahrzeit (15th of Cheshvan)",
       "date": "2023-10-30",
       "memo": "Hebcal joins you in remembering Example2, whose 15th Yahrzeit occurs on Monday, October 30, corresponding to the 15th of Cheshvan, 5784.\n\nExample2's Yahrzeit begins at sundown on Sunday, October 29 and continues until sundown on the day of observance. It is customary to light a memorial candle at sundown as the Yahrzeit begins.\n\nMay your loved one's soul be bound up in the bond of eternal life and may their memory serve as a continued source of inspiration and comfort to you."
     },
     {
       "title": "Example1's 41st Hebrew Birthday (3rd of Iyyar)",
       "date": "2024-05-11",
       "memo": "Hebcal joins you in honoring Example1, whose 41st Hebrew Birthday occurs on Saturday, May 11, corresponding to the 3rd of Iyyar, 5784.\n\nExample1's Hebrew Birthday begins at sundown on Friday, May 10 and continues until sundown on the day of observance."
     }
   ]
 } 

Zmanim (halachic times) API

Hebcal.com now offers a REST API for calculating zmanim (halachic times) for a given location. The basic URL format is as follows:

https://www.hebcal.com/zmanim?cfg=json&geonameid=3448439&date=2021-03-23

Note the following required parameter and its meaning:

  • cfg=json – output JSON

Location must be specified by one of the following mutually exclusive parameters:

  • GeoNames.org numeric ID
    • requires additional parameter geonameid=3448439
    • Hebcal.com supports approximately 47,000 different GeoNames IDs. These are cities with a population of 5000+. See cities5000.zip from https://download.geonames.org/export/dump/.
  • United States ZIP code
    • requires additional parameter zip=90210
  • One of 400 legacy Hebcal city identifiers
    • requires additional parameter city=GB-London
  • Geographic position: location specified by latitude, longitude, and timezone. Requires additional 3 parameters:
    • latitude=[-90 to 90] – latitude in decimal format (e.g. 31.76904 or -23.5475)
    • longitude=[-180 to 180] – longitude decimal format (e.g. 35.21633 or -46.63611)
    • tzid=TimezoneIdentifier (See List of tz database time zones)

Note the following optional date parameters and their meanings:

  • date=2021-03-23 – calculate zmanim for a single date using YYYY-MM-DD format (defaults to today if not specified)
  • start=2021-01-15&end=2021-01-22 – calculate zmanim for a date range using YYYY-MM-DD format

The following Zmanim are included in the response:

chatzotNight – Midnight – Chatzot
Sunset plus 6 halachic hours
alotHaShachar – Dawn – Alot haShachar
Sun is 16.1° below the horizon in the morning
misheyakir – Earliest talis & tefillin – Misheyakir
Sun is 11.5° below the horizon in the morning
misheyakirMachmir – Earliest talis & tefillin – Misheyakir Machmir
Sun is 10.2° below the horizon in the morning
dawn – Civil dawn
Sun is 6° below the horizon in the morning
sunrise – Sunrise
Upper edge of the Sun appears over the eastern horizon in the morning (0.833° above horizon)
sofZmanShma – Latest Shema (Gra)
Sunrise plus 3 halachic hours, according to the Gra
sofZmanTfilla – Latest Shacharit (Gra)
Sunrise plus 4.5 halachic hours, according to the Gra
chatzot – Midday – Chatzot
Sunrise plus 6 halachic hours
minchaGedola – Earliest Mincha – Mincha Gedola
Sunrise plus 6.5 halachic hours
minchaKetana – Preferable earliest time to recite Minchah – Mincha Ketana
Sunrise plus 9.5 halachic hours
plagHaMincha – Plag haMincha
Sunrise plus 10.75 halachic hours
sunset – Sunset
When the upper edge of the Sun disappears below the horizon (0.833° below horizon)
dusk – Civil dusk
Sun is 6° below the horizon in the evening
tzeit7083deg – Nightfall (3 medium stars) – Tzeit 7.083°
When 3 medium stars are observable in the night sky with the naked eye (sun 7.083° below the horizon)
tzeit85deg – Nightfall (3 small stars) – Tzeit 8.5°
When 3 small stars are observable in the night sky with the naked eye (sun 8.5° below the horizon)
tzeit42min – Nightfall (3 medium stars) – Tzeit 42 minutes
When 3 medium stars are observable in the night sky with the naked eye (fixed 42 minutes after sunset)
tzeit50min – Nightfall (3 small stars) – Tzeit 50 minutes
When 3 small stars are observable in the night sky with the naked eye (fixed 50 minutes after sunset)
tzeit72min – Nightfall (Rabbeinu Tam) – Tzeit 72 minutes
When 3 small stars are observable in the night sky with the naked eye (fixed 72 minutes after sunset)

Hebcal 2020 year-end updates

At the conclusion of Gregorian year 2020, we’d like to express our thanks and gratitude to all of our Hebcal.com users. Our mission is to increase awareness of Jewish holidays and to help Jews to be observant of the mitzvot, and many of you have been visiting our site for calendar updates and Hebrew date conversion for years.

Here is a summary of updates we’ve made to Hebcal.com during the past 6 months.

Yahrzeit, Birthday and Anniversary calendar

We now offer annual email reminders for our Yahrzeit, Birthday and Anniversary calendar. After entering and confirming your email address, you will receive a reminder email 7 days before each anniversary. Our email privacy policy is the same as for our Shabbat weekly email list: We will never sell or give your email address to anyone. We will never use your email address to send you unsolicited offers.

In addition, Yahrzeit and anniversary calendar downloads for Apple, Google & Outlook now support more than 3 names. Just click the “+ Add another name” button to create another row and enter the additional details.

Zmanim (halachic times)

In August 2020 we updated our solar calculation engine, which has enabled several new features:

Havdalah can now be calculated according to tzeit hakochavim, the point when 3 small stars are observable in the night time sky with the naked eye. The new default Havdalah option is calculated when the sun is 8.5° below the horizon. This option is an excellent default for most places on the planet. We still offer the option to use a fixed number of minutes past sundown (e.g. 42 min for three medium-sized stars, 50 min for three small stars, 72 min for Rabbeinu Tam) which works well for Israel, most of the USA and Europe.

Fast start and end times are now provided for major fast (Tish’a B’Av) and minor fasts (Ta’anit Esther, Tzom Gedaliah, Tzom Tammuz, Asara B’Tevet, & Ta’anit Bechorot). Minor fasts begin at alot hashachar (when the sun is 16.1° below the horizon in the morning) and end when 3 medium-sized stars are observable in the night sky (when the sun is 7.083° below the horizon in the evening). Tish’a B’Av fast begins at sundown and ends when 3 medium-sized stars are observable.

Chanukah candle-lighting has been updated to occur at dusk on weekdays (when the sun is 6° below the horizon in the evening). To avoid any conflict with Shabbat, candle-lighting times for Chanukah on Friday night are 18 minutes before sundown (same as regular Shabbat candle-lighting) and at regular Havdalah time on Saturday night.

Language support

Earlier in December, we added Spanish language support for event title translations and transliterations. Hebcal now supports the following languages:

  • Sephardic transliterations
  • Ashkenazis transliterations
  • Hebrew – עברית
  • Spanish – español
  • French – français
  • Russian – ру́сский язы́к
  • Polish – język polski
  • Finnish – Suomalainen
  • Hungarian – Magyar nyelv
  • Sephardic translit. + Hebrew
  • Ashkenazis translit. + Hebrew

These languages are fully supported on the Custom Calendar generator and its associated export formats (Apple, Google, iCalendar, CSV, Print PDF) and the printable Candle-lighting Times Year at a Glance (“refrigerator times”) page.

Torah Readings

Holiday Torah readings are now included in the description/memo section of Apple, Google, & Outlook calendar feeds and our downloadable Torah reading spreadsheets (aliyah-by-aliyah breakdown especially useful for synagogue or minyan leyning coordinators). Previously only regular Shabbat Torah readings were included.

Aliyot for special Shabbatot that include three Sifrei Torah have been improved. We read from three Sifrei Torah when Rosh Chodesh coincides with Shabbat HaCodesh, Shabbat Shekalim or Shabbat Chanukah. Although some minyanim have the custom of reading 8 aliyot, we now take the more common approach of including the typical 7 aliyot for Shabbat. The 1st Sefer Torah is for regular Torah reading (aliyot 1-6), the 2nd Sefer Torah is read for the 7th aliyah for Rosh Chodesh (Numbers 28:9-15) and the 3rd Sefer Torah is read for the maftir aliyah (the special Shabbat).

Triennial Torah reading is now supported for Hebrew years 5745 through 5830 (Gregorian years 1984 – 2070).

Parsha detail pages now take into consideration the differences between the Israel and Diaspora sedra schemes. For example, in the year 5782 Parashat Achrei Mot is read on April 30, 2022 in the Diaspora and on April 23, 2022 in Israel.

Miscellaneous

Hebrew Date Converter now lists holidays and Parsha HaShavuah for any date from the year 0001-9999. Previously it converted dates but only mentioned holidays & parsha for years 1900-2099.

When the 9th of Av falls on Shabbat and the Tish’a B’Av fast is postponed to the 10th, the calendar event now says “Tish’a B’Av (observed)”.

The Hebrew typeface used on the website is now SBL Hebrew Font (copyright Society of Biblical Literature and Tiro Typeworks). This typeface is a more traditional serif style, which improves legibility.

We have discontinued support for Palm DateBook Archive calendar downloads.

How accurate are candle lighting times?

Candle-lighting and Havdalah times are derived from sunset times, which are approximated from a location (latitude, longitude) and day of year. As of August 2020, Hebcal.com uses a sunset algorithm published by the US National Oceanic and Atmospheric Administration. The NOAA claims accuracy within 2 minutes except at extreme northern or southern latitudes.

Differences of 1-2 minutes between Hebcal and other sources publishing candle lighting times or sunset times are expected. Remember that candle lighting times can only be approximated based on location. Here are a few common reasons why you may see differences in candle lighting times:

  1. Different minhag on when to light candles. Hebcal defaults to 18 minutes before sundown for most locations (40 minutes before sundown for Jerusalem). Other sources may use 20 minutes before sundown. Hebcal gives an option to specify a different number of minutes before sunset if you don’t follow the 18-minute minhag.
  2. Slightly different sunset calculators. The sunset calculator we use on Hebcal.com as of August 2020 uses an algorithm published by the US National Oceanic and Atmospheric Administration. Hebcal’s NOAA algorithm is implemented in JavaScript using double-precision floating point arithmetic. Other sources may use a slightly different algorithm, for example one by Jean Meeus. However, even if the other source also uses the NOAA algorithm, the implementation could differ slightly; there are many constants and opportunities to round and truncate which could result in slight differences in the final calculated sunset time for a given day and location.
  3. Slightly different latitude/longitude definitions for a given city. Since 2013, Hebcal.com has been using lat/long definitions from GeoNames.org, which is available under a Creative Commons license. For the USA, we purchase a commercial ZIP code database from zip-codes.com. For very large cities, the sunset at the east side of the city might be a minute earlier than the west side of the city.
  4. Deliberate rounding down (or up). Hebcal rounds candle lighting (Friday) times down to the nearest minute, and rounds Havdalah times up to the nearest minute. To be more precise, we use the floor minute for candle-lighting, and we use the standard mathematical rounding rule for Havdalah. The idea here is that it’s better to display candle-lighting time as much as 59 seconds earlier than strictly necessary, and for Havdalah it’s better to wait an additional 30 seconds to end Shabbat/yontiff.
    • For example, if the exact candle lighting time from the sunset engine (including seconds) was at 20:02:31 or even 20:02:59, Hebcal displays candle-lighting as 20:02.
    • On the other hand, if the Havdalah calculation is 21:17:29, Hebcal will display 21:17. If it were 21:17:30 through 21:17:59, Hebcal displays 21:18.

As of August 2020, options for Havdalah times have also changed. Hebcal now offers an option to use tzeit hakochavim, the point when 3 small stars are observable in the night sky with the naked eye (sun 8.5° below the horizon). This option is an excellent default for most places on the planet. We also offer the option to use a fixed number of minutes past sundown. Typically one would enter 42 min for three medium-sized stars, 50 min for three small stars, 72 min for Rabbeinu Tam, or 0 to suppress Havdalah times.

Lastly, remember that the NOAA algorithm can only approximate the candle-lighting times for your location. If you ever have any doubts about Hebcal’s times, consult your local halachic authority.

Hebcal Developer API minor updates

We’re pleased to share a couple of brief and minor updates to our collection of Developer APIs.

  1. We now recommend using HTTPS for all of our APIs. We’ve updated our documentation to reflect this. Most of our JSON APIs still support HTTP. Some of our APIs now return a 301 redirect from the HTTP version to the HTTPS version.
  2. We implemented some simplistic rate-limiting to throttle clients who are sending too many API queries. You may receive a 429 “Too Many Requests” error if your client makes more than 90 requests in a 10-second window. Remember, this is a free service; please be polite and send batch API requests slowly over a longer period of time.