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&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:

  • 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
    • i=off – Diaspora sedra scheme
    • i=on – Israel sedra scheme
  • c=on – Candle lighting times. See also candle-lighting options below.
    • m=50 – Havdalah 50 minutes after sundown. Set to m=0 (zero) to disable Havdalah times
    • b=18 – Candle-lighting time minutes before sunset
  • 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 location for candle-lighting times:

  • geo=none – no candle-lighting location (default)
  • 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 7 parameters:
    • ladeg=[0-90] – latitude degrees
    • lamin=[0-60] – latitude minutes
    • ladir={n,s} – latitude direction (North or South)
    • lodeg=[0-180] – longitude degrees
    • lomin=[0-60] -longitude minutes
    • lodir={e,w} -longitude direction (East or West)
    • tzid=TimezoneIdentifier (See List of tz database time zones)

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:

{
    "link": "http://www.hebcal.com/hebcal/?v=1;nx=on;year=2015;month=5;ss=on;mf=on;c=on;geo=geoname;geonameid=3448439;m=50;s=on;maj=on;min=on;mod=on",
    "latitude": -23.5475,
    "longitude": -46.63611,
    "title": "Hebcal May 2015 São Paulo, Brazil",
    "date": "2014-11-30T06:53:48-00:00",
    "location": {
        "geonameid": 3448439,
        "latitude": -23.5475,
        "tzid": "America/Sao_Paulo",
        "geo": "geoname",
        "title": "São Paulo, Brazil",
        "city": "São Paulo",
        "longitude": -46.63611
    },
    "items": [{
        "category": "candles",
        "title": "Candle lighting: 5:11pm",
        "date": "2015-05-22T17:11:00-03:00"
    }, {
        "date": "2015-05-23",
        "hebrew": "פרשת במדבר",
        "title": "Parashat Bamidbar",
        "link": "http://www.hebcal.com/sedrot/bamidbar",
        "category": "parashat"
    }, {
        "category": "holiday",
        "link": "http://www.hebcal.com/holidays/shavuot",
        "hebrew": "ערב שבועות",
        "date": "2015-05-23",
        "title": "Erev Shavuot"
    }, {
        "date": "2015-05-23T18:19:00-03:00",
        "title": "Candle lighting: 6:19pm",
        "category": "candles"
    }, {
        "link": "http://www.hebcal.com/holidays/shavuot",
        "hebrew": "שבועות יום א׳",
        "date": "2015-05-24",
        "title": "Shavuot I",
        "yomtov": true,
        "category": "holiday"
    }, {
        "category": "holiday",
        "yomtov": true,
        "title": "Shavuot II",
        "hebrew": "שבועות יום ב׳",
        "date": "2015-05-25",
        "link": "http://www.hebcal.com/holidays/shavuot"
    }, {
        "category": "havdalah",
        "title": "Havdalah (50 min): 6:18pm",
        "date": "2015-05-25T18:18:00-03:00"
    }]
}

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