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

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=50

Note the following customizable parameters and their meanings:

  • cfg=json – output format is JSON (cfg=json) or RSS (cfg=r)
  • m=50 – Havdalah 50 minutes after sundown. Set to m=0 (zero) to disable Havdalah times
  • b=18 – Candle-lighting time minutes before sunset
  • a=off – use Sephardic (a=off) or Ashkenazis transliterations (a=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)

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

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

Mutually exclusive language parameter:

  • lg=s – Sephardic transliterations (default if unspecified)
  • lg=sh – Sephardic translit. + Hebrew
  • lg=a – Ashkenazis transliterations
  • lg=ah – Ashkenazis translit. + Hebrew
  • lg=h – Hebrew only

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.

Display a Jewish Calendar on your website with Hebcal + FullCalendar.io

To display a Jewish calendar on your website, you can use event data from Hebcal.com and the open source JavaScript event calendar from fullcalendar.io.

First, you’ll want to start by including the CSS and JS in your header, per the FullCalendar Basic Usage.

Then, for the events configuration, use a url that references our Jewish calendar REST API, but change cfg=json to cfg=fc.

You won’t need to specify a year=YYYY parameter, as the fullcalendar.io script automatically sends start=YYYY-MM-DD and end=YYYY-MM-DD parameters for you.

For best performance, be sure to use cache: true.

Here’s the FullCalendar invocation:

If you’d like to include candle-lighting times for Shabbat and holidays, be sure to adjust the url parameter to include c=on and one of the location fields (such as geonameid=3448439 for São Paulo, Brazil).

We recommend some specific styles to make the page look prettier:

Here’s a complete example that uses the aforementioned JS + CSS, and also includes the necessary stuff to load FullCalendar.io and dependencies via CDN:

Hebrew Date Converter REST API

We offer a simple API for converting between Gregorian and Hebrew dates. Two output formats are supported: JSON and XML.

To convert from Gregorian to Hebrew date use this URL format:

https://www.hebcal.com/converter/?cfg=json&gy=2011&gm=6&gd=2&g2h=1

  • gy=2011 – Gregorian year
  • gm=6 – Gregorian month (1=January, 12=December)
  • gd=2 – Gregorian day of month
  • g2h=1 – Convert from Gregorian to Hebrew date
  • gs=on – After sunset on Gregorian date
  • cfg=json – output format is JSON (cfg=json) or XML (cfg=xml)

To convert from Hebrew to Gregorian use this URL format:

https://www.hebcal.com/converter/?cfg=json&hy=5749&hm=Kislev&hd=25&h2g=1

  • hy=5749 – Hebrew year
  • hm=Kislev – Hebrew month (Nisan, Iyyar, Sivan, Tamuz, Av, Elul, Tishrei, Cheshvan, Kislev, Tevet, Shvat, Adar1, Adar2)
  • hd=25 – Hebrew day of month
  • h2g=1 – Convert from Hebrew to Gregorian date
  • cfg=json – output format is JSON (cfg=json) or XML (cfg=xml)

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 (_).

Sample output in JSON and XML: