Currently Viewing Posts in Developers, APIs, RSS Feeds, Source Code

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

Shabbat times REST API

Much like our full Jewish calendar REST API, we offer a simple API for getting just this week’s Shabbat times and Torah Portion. Two output formats are supported: JSON and RSS.

The basic URL format is as follows:

https://www.hebcal.com/shabbat?cfg=json&geonameid=3448439&M=on

Note the following customizable parameters and their meanings:

  • cfg=json – output format is JSON (cfg=json) or RSS (cfg=r)
  • b=18 – Candle-lighting time minutes before sunset (the default is 18). For Jerusalem, the default is b=40
  • M=on – Havdalah at nightfall – 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)
  • m=50 – Havdalah 50 minutes after sundown. This option is available for those whose minhag is to end Shabbat a fixed number of minutes after 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. Set to m=0 (zero) to disable Havdalah times
  • a=off – use Sephardic (a=off) or Ashkenazis transliterations (a=on)
  • leyning=off – include Torah and Haftarah for regular Shabbat (default on)

You must specify a location for candle-lighting times:

  • geo=geoname – location specified by 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 http://download.geonames.org/export/dump/.
  • geo=zip – location specified by United States ZIP code
    • requires additional parameter zip=90210
  • geo=city – location specified by one of the Hebcal.com legacy city identifiers
    • requires additional parameter city=GB-London
  • geo=pos – 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)

You may optionally specify a language parameter lg={s,a,h,es,de,ru,fr,…} for event name transliterations.

You can optionally specify an exact date, for example 13 February 2021. If unspecified, defaults to today.

  • gy=2021&gm=2&gd=13

And example output looks like this:

Jewish calendar REST API

Hebcal.com offers a REST API for fetching Jewish calendar data. The output format is in JSON.

The basic URL format is as follows:

https://www.hebcal.com/hebcal?v=1&cfg=json&maj=on&min=on&mod=on&nx=on&year=now&month=x&ss=on&mf=on&c=on&geo=geoname&geonameid=3448439&m=50&s=on

Note the following customizable parameters and their meanings:

  • v=1 – version. Required.
  • cfg=json – output JSON instead of HTML. Also variant cfg=fc for fullcalendar.io integration
  • year=now – “now” for current year, or 4-digit YYYY such as 2003
  • month=x – “x” for entire Gregorian year, or use a numeric month (1=January, 6=June, etc.)
  • maj=on – Major holidays
  • min=on – Minor holidays (Tu BiShvat, Lag B’Omer, …)
  • nx=on – Rosh Chodesh
  • mf=on – Minor fasts (Ta’anit Esther, Tzom Gedaliah, …)
  • ss=on – Special Shabbatot (Shabbat Shekalim, Zachor, …)
  • mod=on – Modern holidays (Yom HaShoah, Yom HaAtzma’ut, …)
  • s=on – Parashat ha-Shavuah on Saturday
  • c=on – Candle lighting times. See also candle-lighting options below.
    • b=18 – Candle-lighting time minutes before sunset (the default is 18). For Jerusalem, the default is b=40
    • M=on – Havdalah at nightfall – 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)
    • m=50 – Havdalah 50 minutes after sundown. This option is available for those whose minhag is to end Shabbat a fixed number of minutes after 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. Set to m=0 (zero) to disable Havdalah times
  • D=on – Hebrew date for dates with some event
  • d=on – Hebrew date for entire date range
  • o=on – Days of the Omer

Mutually exclusive options for Diaspora/Israel holidays and Torah Readings:

  • i=off – Diaspora holidays and Torah readings (default if unspecified)
  • i=on – Israel holidays and Torah readings

Mutually exclusive location for candle-lighting times:

  • geo=none – no candle-lighting location (default if unspecified)
  • geo=geoname – location specified by 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/.
  • geo=zip – location specified by United States ZIP code
    • requires additional parameter zip=90210
  • geo=city – location specified by one of the Hebcal.com legacy city identifiers
    • requires additional parameter city=GB-London
  • geo=pos – 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)

Mutually exclusive language parameter for event name transliterations:

lg= Meaning
s Sephardic transliterations (default if unspecified)
sh Sephardic translit. + Hebrew
a Ashkenazis transliterations
ah Ashkenazis translit. + Hebrew
h Hebrew – עברית
de German – Deutsch
es Spanish – Español
fr French – français
ru Russian – ру́сский язы́к
pl Polish – język polski
fi Finnish – Suomalainen
hu Hungarian – Magyar nyelv

Optional callback parameter:

  • callback=function – wraps the JSON output text in parentheses and a function name of your choosing. Callback function names may only use upper and lowercase alphabetic characters (A-Z, a-z), numbers (0-9), the period (.), the underscore (_).

And example output looks like this:

If you don’t want candle lighting times, just use c=off and omit the zip and m parameters.