Posted by & filed under Developers, APIs, RSS Feeds, Source Code.

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

The basic URL format is as follows:

http://www.hebcal.com/hebcal/?v=1&cfg=json&nh=on&nx=on&year=now&month=x&ss=on&mf=on&c=on&zip=90210&m=72&s=on

Note the following customizable parameters and their meanings:

  • 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.)
  • nh=on – Major holidays
  • nx=on – Rosh Chodesh
  • mf=on – Minor fasts
  • ss=on – Special Shabbatot
  • s=on – Parashat ha-Shavuah on Saturday
    • i=off – Diaspora sedra scheme
    • i=on – Israel sedra scheme
  • c=on – Candle lighting times
    • zip=90210 – use zip code 90210 for candle lighting times
    • m=72 – Havdalah 72 minutes after sundown. 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

Note mutually exclusive language parameter:

  • lg=s – Sephardic transliterations
  • lg=sh – Sephardic translit. + Hebrew
  • lg=a – Ashkenazis transliterations
  • lg=ah – Ashkenazis translit. + Hebrew
  • lg=h – Hebrew only

Note also an 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:

{
   "title":"Hebcal 2013 Beverly Hills, CA 90210",
   "link":"http://www.hebcal.com/hebcal/?v=1;nh=on;nx=on;year=2013;month=x;ss=on;mf=on;c=on;zip=90210;m=72;s=on;geo=zip;tz=-8;dst=usa",
   "date":"2013-05-24T16:13:20-00:00",
   "latitude":34.0925,
   "longitude":-118.4099,
   "items":[
      {
         "title":"Candle lighting: 4:39pm",
         "category":"candles",
         "date":"2013-01-04T16:39:00-08:00"
      },
      {
         "title":"Parashat Shemot",
         "category":"parashat",
         "date":"2013-01-05",
         "link":"http://www.hebcal.com/sedrot/shemot",
         "hebrew":"פרשת שמות"
      },
      {
         "title":"Havdalah (72 min): 6:10pm",
         "category":"havdalah",
         "date":"2013-01-05T18:10:00-08:00"
      },
      {
         "title":"Tu BiShvat",
         "category":"holiday",
         "date":"2013-01-26",
         "link":"http://www.hebcal.com/holidays/tu-bishvat",
         "hebrew":"טו בשבט"
      }
   ]
}

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