Skip to main content

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 over 100,000 different GeoNames IDs. These are world cities with a population of 1,000 or more. See cities1000.zip from https://download.geonames.org/export/dump/.
  • geo=zip – location specified by United States ZIP code
    • requires additional parameter zip=90210
  • geo=pos – location specified by latitude, longitude, and timezone. Requires additional 3 parameters:
    • latitude=[-90.0 to 90.0] – latitude in decimal format (e.g. 31.76904 or -23.5475)
    • longitude=[-180.0 to 180.0] – longitude decimal format (e.g. 35.21633 or -46.63611)
    • tzid=TimezoneIdentifier. See List of tz database time zones. Be sure to use the “TZ database name” such as America/New_York or Europe/Paris, not a UTC offset
  • geo=city – location specified by one of ~400 legacy city identifiers
    • requires additional parameter city=GB-London
    • deprecated: geo=geoname is preferred

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

You may optionally add &hdp=1 to include heDateParts field on untimed (all-day) items in the response.

As with all Hebcal.com REST APIs:

  • Both HTTP and HTTPS (HTTP/2) are supported. Although most of the Web has moved to HTTPS, if you wish to reduce CPU overhead on your client you may continue to use plain (port 80) HTTP for API requests
  • We encourage HTTP caching proxies. Proper Cache-Control and Expires are generated in the response
  • We support both gzip and br (brotli) compression; set the appropriate Accept-Encoding header in your request to enable
  • We support HTTP Keep-Alive for multiple requests

Example output

JSON (cfg=json)
{
  "title": "Hebcal São Paulo February 2015",
  "date": "2022-05-30T17:42:57.551Z",
  "location": {
    "title": "São Paulo, Sao Paulo, Brazil",
    "city": "São Paulo",
    "tzid": "America/Sao_Paulo",
    "latitude": -23.5475,
    "longitude": -46.63611,
    "cc": "BR",
    "country": "Brazil",
    "admin1": "Sao Paulo",
    "asciiname": "Sao Paulo",
    "geo": "geoname",
    "geonameid": 3448439
  },
  "range": {
    "start": "2015-02-20",
    "end": "2015-02-21"
  },
  "items": [
    {
      "title": "Rosh Chodesh Adar",
      "date": "2015-02-20",
      "hdate": "1 Adar 5775",
      "category": "roshchodesh",
      "hebrew": "ראש חודש אדר",
      "leyning": {
        "1": "Numbers 28:1-28:3",
        "2": "Numbers 28:3-28:5",
        "3": "Numbers 28:6-28:10",
        "4": "Numbers 28:11-28:15",
        "torah": "Numbers 28:1-15"
      },
      "link": "https://hebcal.com/h/rosh-chodesh-adar-2015?us=js&um=api",
      "memo": "Start of month of Adar on the Hebrew calendar. Adar (אַדָר) is the 12th month of the Hebrew year, has 29 days, and corresponds to February or March on the Gregorian calendar.  רֹאשׁ חוֹדֶשׁ, transliterated Rosh Chodesh or Rosh Hodesh, is a minor holiday that occurs at the beginning of every month in the Hebrew calendar. It is marked by the birth of a new moon"
    },
    {
      "title": "Candle lighting: 7:25pm",
      "date": "2015-02-20T19:25:00-02:00",
      "category": "candles",
      "title_orig": "Candle lighting",
      "hebrew": "הדלקת נרות",
      "memo": "Parashat Terumah"
    },
    {
      "title": "Parashat Terumah",
      "date": "2015-02-21",
      "hdate": "2 Adar 5775",
      "category": "parashat",
      "hebrew": "פרשת תרומה",
      "leyning": {
        "1": "Exodus 25:1-25:16",
        "2": "Exodus 25:17-25:30",
        "3": "Exodus 25:31-26:14",
        "4": "Exodus 26:15-26:30",
        "5": "Exodus 26:31-26:37",
        "6": "Exodus 27:1-27:8",
        "7": "Exodus 27:9-27:19",
        "torah": "Exodus 25:1-27:19",
        "haftarah": "I Kings 5:26-6:13",
        "maftir": "Exodus 27:17-27:19",
        "triennial": {
          "1": "Exodus 26:1-26:3",
          "2": "Exodus 26:4-26:6",
          "3": "Exodus 26:7-26:11",
          "4": "Exodus 26:12-26:14",
          "5": "Exodus 26:15-26:21",
          "6": "Exodus 26:22-26:25",
          "7": "Exodus 26:26-26:30",
          "maftir": "Exodus 26:26-26:30"
        }
      },
      "link": "https://hebcal.com/s/terumah-20150221?us=js&um=api"
    },
    {
      "title": "Havdalah: 8:17pm",
      "date": "2015-02-21T20:17:00-02:00",
      "category": "havdalah",
      "title_orig": "Havdalah",
      "hebrew": "הבדלה"
    }
  ]
}
RSS (cfg=r)
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"
  xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
  xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>Shabbat Times for São Paulo, Sao Paulo, Brazil</title>
    <link>https://www.hebcal.com/shabbat?geonameid=3448439&amp;M=on&amp;lg=s&amp;utm_source=shabbat1c&amp;utm_medium=rss</link>
    <atom:link href="https://www.hebcal.com/shabbat?cfg=r&amp;geonameid=3448439&amp;M=on&amp;lg=s&amp;pubDate=0" rel="self" type="application/rss+xml" />
    <description>Weekly Shabbat candle lighting times for São Paulo, Sao Paulo, Brazil</description>
    <language>en</language>
    <copyright>Copyright (c) 2022 Michael J. Radwin. All rights reserved.</copyright>
    <lastBuildDate>Mon, 30 May 2022 17:47:38 GMT</lastBuildDate>
    <item>
      <title>Rosh Chodesh Adar</title>
      <link>https://hebcal.com/h/rosh-chodesh-adar-2015?us=shabbat1c&amp;um=rss</link>
      <guid isPermaLink="false">https://www.hebcal.com/holidays/rosh-chodesh-adar-2015#20150220-rosh-chodesh-adar</guid>
      <description>Start of month of Adar on the Hebrew calendar. Adar (אַדָר) is the 12th month of the Hebrew year, has 29 days, and corresponds to February or March on the Gregorian calendar.  רֹאשׁ חוֹדֶשׁ, transliterated Rosh Chodesh or Rosh Hodesh, is a minor holiday that occurs at the beginning of every month in the Hebrew calendar. It is marked by the birth of a new moon</description>
      <category>roshchodesh</category>
      <pubDate>Mon, 30 May 2022 17:47:38 GMT</pubDate>
    </item>
    <item>
      <title>Candle lighting: 7:25pm</title>
      <link>https://www.hebcal.com/shabbat?geonameid=3448439&amp;M=on&amp;lg=s&amp;dt=2015-02-20&amp;utm_source=shabbat1c&amp;utm_medium=rss#20150220-candle-lighting</link>
      <guid isPermaLink="false">https://www.hebcal.com/shabbat?geonameid=3448439&amp;M=on&amp;lg=s&amp;dt=2015-02-20#20150220-candle-lighting</guid>
      <description>Friday, February 20, 2015</description>
      <category>candles</category>
      <pubDate>Mon, 30 May 2022 17:47:38 GMT</pubDate>
      <geo:lat>-23.5475</geo:lat>
      <geo:long>-46.63611</geo:long>
    </item>
    <item>
      <title>Parashat Terumah</title>
      <link>https://hebcal.com/s/terumah-20150221?us=shabbat1c&amp;um=rss</link>
      <guid isPermaLink="false">https://www.hebcal.com/sedrot/terumah-20150221#20150221-parashat-terumah</guid>
      <description>Torah: Exodus 25:1-27:19
Haftarah: I Kings 5:26-6:13</description>
      <category>parashat</category>
      <pubDate>Mon, 30 May 2022 17:47:38 GMT</pubDate>
    </item>
    <item>
      <title>Havdalah: 8:17pm</title>
      <link>https://www.hebcal.com/shabbat?geonameid=3448439&amp;M=on&amp;lg=s&amp;dt=2015-02-21&amp;utm_source=shabbat1c&amp;utm_medium=rss#20150221-havdalah</link>
      <guid isPermaLink="false">https://www.hebcal.com/shabbat?geonameid=3448439&amp;M=on&amp;lg=s&amp;dt=2015-02-21#20150221-havdalah</guid>
      <description>Saturday, February 21, 2015</description>
      <category>havdalah</category>
      <pubDate>Mon, 30 May 2022 17:47:38 GMT</pubDate>
    </item>
  </channel>
</rss>

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=on&s=on

As with all Hebcal.com REST APIs:

  • Both HTTP and HTTPS (HTTP/1.1 and HTTP/2) are supported.
    • You may continue to use plain (port 80) HTTP for API requests if you wish to reduce CPU overhead on your client
  • To encourage HTTP caching proxies, proper Cache-Control and Expires are generated in the response
  • Compression is supported and encouraged; set the Accept-Encoding: br request header for brotli (best option) or Accept-Encoding: gzip (also very good)
  • HTTP Keep-Alive is supported for multiple subsequent requests without the overhead of TCP handshaking

Parameters and their meanings

  • v=1 – version. Required.
  • cfg=json – output JSON instead of HTML
    • cfg=json for JSON format (described in more detail below)
    • cfg=fc for fullcalendar.io integration
    • cfg=rss for RSS (Atom 1.0)
    • cfg=ics for iCalendar RFC 5545
    • cfg=csv for Comma Separated Values

Date

Date range may be specified either using year or both start and end:

  • year=now – “now” for current year, or 4-digit YYYY such as 2003
    • yt=G – Interpret year as Gregorian year (common era) – default
    • yt=H – Interpret year as Hebrew year (e.g. 5782)
    • month=x – default “x” for entire Gregorian year, or use a numeric month (1=January, 6=June, etc.)
  • start=2021-12-29 – Gregorian start date in YYYY-MM-DD format
  • end=2022-01-04 – Gregorian end date in YYYY-MM-DD format

Event options

All booleans, default “off”

  • 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
    • leyning=off – reduce size of JSON by disabling the full kriyah/triennial Torah reading and aliyot details (default on when s=on)
  • D=on – Hebrew date for dates with some event
  • d=on – Hebrew date for entire date range
  • o=on – Days of the Omer
  • F=on – Daf Yomi
  • myomi=on – Mishna Yomi

Diaspora vs. Israel schedule for holidays and Torah Readings

Mutually exclusive options:

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

Candle-lighting and fast start/end times

  • c=on – Candle lighting times. Requires location, see below.
  • b=18 – Candle-lighting time minutes before sunset (the default is 18). For Jerusalem, the default is b=40
  • M=on – calculate 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 is the default, and this option is an excellent default for most places on the planet.
  • m=50 – calculate Havdalah as fixed 50 minutes after sundown. This option is used by 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.

Location

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 over 100,000 different GeoNames IDs. These are world cities with a population of 1,000 or more. See cities1000.zip from https://download.geonames.org/export/dump/.
  • geo=zip – location specified by United States ZIP code
    • requires additional parameter zip=90210
  • geo=pos – location specified by latitude, longitude, and timezone. Requires additional 3 parameters:
    • latitude=[-90.0 to 90.0] – latitude in decimal format (e.g. 31.76904 or -23.5475)
    • longitude=[-180.0 to 180.0] – longitude decimal format (e.g. 35.21633 or -46.63611)
    • tzid=TimezoneIdentifier. See List of tz database time zones. Be sure to use the “TZ database name” such as America/New_York or Europe/Paris, not a UTC offset
  • geo=city – location specified by one of ~400 legacy city identifiers
    • requires additional parameter city=GB-London
    • deprecated: geo=geoname is preferred

Language

Mutually exclusive language parameter for event name transliterations:

lg= Meaning
s Sephardic transliterations (default if unspecified)
a Ashkenazic transliterations
he 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
ro Română – Romanian
ashkenazi_romanian Română (Ashk.) – Romanian (Ashk.)
uk українська – Ukrainian
sh Sephardic translit. + Hebrew
ah Ashkenazis translit. + Hebrew

Miscellaneous

Add &hdp=1 to include heDateParts field on untimed (all-day) items in the response.

Callback

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

Example output

{
  "title": "Hebcal São Paulo May 2015",
  "date": "2022-05-30T17:38:40.629Z",
  "location": {
    "title": "São Paulo, Sao Paulo, Brazil",
    "city": "São Paulo",
    "tzid": "America/Sao_Paulo",
    "latitude": -23.5475,
    "longitude": -46.63611,
    "cc": "BR",
    "country": "Brazil",
    "admin1": "Sao Paulo",
    "asciiname": "Sao Paulo",
    "geo": "geoname",
    "geonameid": 3448439
  },
  "range": {
    "start": "2015-05-22",
    "end": "2015-05-25"
  },
  "items": [
    {
      "title": "Candle lighting: 5:11pm",
      "date": "2015-05-22T17:11:00-03:00",
      "category": "candles",
      "title_orig": "Candle lighting",
      "hebrew": "הדלקת נרות",
      "memo": "Parashat Bamidbar"
    },
    {
      "title": "Erev Shavuot",
      "date": "2015-05-23",
      "hdate": "5 Sivan 5775",
      "category": "holiday",
      "subcat": "major",
      "hebrew": "ערב שבועות",
      "link": "https://hebcal.com/h/shavuot-2015?us=js&um=api",
      "memo": "Festival of Weeks. Commemorates the giving of the Torah at Mount Sinai"
    },
    {
      "title": "Parashat Bamidbar",
      "date": "2015-05-23",
      "hdate": "5 Sivan 5775",
      "category": "parashat",
      "hebrew": "פרשת במדבר",
      "leyning": {
        "1": "Numbers 1:1-1:19",
        "2": "Numbers 1:20-1:54",
        "3": "Numbers 2:1-2:34",
        "4": "Numbers 3:1-3:13",
        "5": "Numbers 3:14-3:39",
        "6": "Numbers 3:40-3:51",
        "7": "Numbers 4:1-4:20",
        "torah": "Numbers 1:1-4:20",
        "haftarah": "Hosea 2:1-22",
        "maftir": "Numbers 4:17-4:20",
        "triennial": {
          "1": "Numbers 2:1-2:9",
          "2": "Numbers 2:10-2:16",
          "3": "Numbers 2:17-2:24",
          "4": "Numbers 2:25-2:31",
          "5": "Numbers 2:32-2:34",
          "6": "Numbers 3:1-3:4",
          "7": "Numbers 3:5-3:13",
          "maftir": "Numbers 3:11-3:13"
        }
      },
      "link": "https://hebcal.com/s/bamidbar-20150523?us=js&um=api"
    },
    {
      "title": "Candle lighting: 6:05pm",
      "date": "2015-05-23T18:05:00-03:00",
      "category": "candles",
      "title_orig": "Candle lighting",
      "hebrew": "הדלקת נרות",
      "memo": "Erev Shavuot"
    },
    {
      "title": "Shavuot I",
      "date": "2015-05-24",
      "hdate": "6 Sivan 5775",
      "category": "holiday",
      "subcat": "major",
      "yomtov": true,
      "hebrew": "שבועות א׳",
      "leyning": {
        "1": "Exodus 19:1-19:6",
        "2": "Exodus 19:7-19:13",
        "3": "Exodus 19:14-19:19",
        "4": "Exodus 19:20-20:14",
        "5": "Exodus 20:15-20:23",
        "torah": "Exodus 19:1-20:23; Numbers 28:26-31",
        "haftarah": "Ezekiel 1:1-28, 3:12",
        "maftir": "Numbers 28:26-28:31"
      },
      "link": "https://hebcal.com/h/shavuot-2015?us=js&um=api",
      "memo": "Festival of Weeks. Commemorates the giving of the Torah at Mount Sinai"
    },
    {
      "title": "Candle lighting: 6:05pm",
      "date": "2015-05-24T18:05:00-03:00",
      "category": "candles",
      "title_orig": "Candle lighting",
      "hebrew": "הדלקת נרות",
      "memo": "Shavuot I"
    },
    {
      "title": "Shavuot II",
      "date": "2015-05-25",
      "hdate": "7 Sivan 5775",
      "category": "holiday",
      "subcat": "major",
      "yomtov": true,
      "hebrew": "שבועות ב׳",
      "leyning": {
        "1": "Deuteronomy 15:19-15:23",
        "2": "Deuteronomy 16:1-16:3",
        "3": "Deuteronomy 16:4-16:8",
        "4": "Deuteronomy 16:9-16:12",
        "5": "Deuteronomy 16:13-16:17",
        "torah": "Deuteronomy 15:19-16:17; Numbers 28:26-31",
        "haftarah": "Habakkuk 3:1-19",
        "maftir": "Numbers 28:26-28:31"
      },
      "link": "https://hebcal.com/h/shavuot-2015?us=js&um=api",
      "memo": "Festival of Weeks. Commemorates the giving of the Torah at Mount Sinai"
    },
    {
      "title": "Havdalah: 6:05pm",
      "date": "2015-05-25T18:05:00-03:00",
      "category": "havdalah",
      "title_orig": "Havdalah",
      "hebrew": "הבדלה",
      "memo": "Shavuot II"
    }
  ]
}

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

Example 2: Daf Yomi only

To get only the Daf Yomi for a given day (and not holidays) you can construct a URL that looks like this:

https://www.hebcal.com/hebcal?cfg=json&v=1&F=on&start=2022-06-07&end=2022-06-07

Example output:

{
  "title": "Hebcal Diaspora June 2022",
  "date": "2022-06-03T15:52:37.011Z",
  "location": {
    "geo": "none"
  },
  "range": {
    "start": "2022-06-06",
    "end": "2022-06-06"
  },
  "items": [
    {
      "title": "Yevamot 91",
      "date": "2022-06-06",
      "hdate": "7 Sivan 5782",
      "category": "dafyomi",
      "hebrew": "יבמות 91",
      "link": "https://www.sefaria.org/Yevamot.91a?lang=bi&utm_source=hebcal.com&utm_medium=api"
    }
  ]
}

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.

Here’s a quick template to give you an idea of how to edit the HTML on your site.

<!DOCTYPE html>
<html lang="en"><head>
<meta charset="utf-8">
<title>Jewish Calendar</title>
<link href="hebcal-styles.css" rel="stylesheet">
</head>
<body>
<div id="calendar"></div>
<script src="https://cdn.jsdelivr.net/npm/fullcalendar@6.0.3/index.global.min.js"></script>
<script>
document.addEventListener('DOMContentLoaded', function() {
  var calendarEl = document.getElementById('calendar');
  var calendar = new FullCalendar.Calendar(calendarEl, {
      headerToolbar: {
        left: 'title',
        right: 'prev,next today',
      },
      events: {
          // add &c=on&geonameid=[locationID] for candle-lighting times
          url: "https://www.hebcal.com/hebcal?cfg=fc&v=1&i=off&maj=on&min=on&nx=on&mf=on&ss=on&mod=on&lg=s&s=on",
          cache: true
      }
  });
  calendar.render();
  // optional: bind keyboard left/right arrow keys
  // to move calendar forward/backward by a month
  document.addEventListener('keydown', function(e) {
    if (e.key === 'ArrowLeft' && !e.metaKey) {
      calendar.prev();
    } else if (e.key === 'ArrowRight' && !e.metaKey) {
      calendar.next();
    }
  });
});
</script>
</body>
</html>

Note on line 9 we use the CDN-hosted FullCalendar JavaScript. If you want to self-host the FullCalendar, you can do so following the FullCalendar Basic Usage instructions.

Note lines 18-22 where we specify the FullCalendar events configuration. We use a url on line 20 that fetches events from Hebcal. You can make other changes such as enabling candle-lighting times, Daf Yomi, etc and changing the event display language (default Sephardic transliterations). See the Jewish calendar REST API documentation for full details on what each parameter means. Remember to use cfg=fc for the FullCalendar format.

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 (line 21).

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:

/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */
html, body {
  margin: 0;
  padding: 0;
  font-family: Arial, 'Helvetica Neue', Helvetica, sans-serif;
  font-size: 14px;
}
#calendar {
  max-width: 1000px;
  margin: 40px auto;
}
a:hover .fc-event-title {
  text-decoration: underline;
}
a:not([href]):hover .fc-event-title {
  text-decoration: none;
}
.fc-event {
    display: block; /* make the <a> tag block */
    font-size: .85em;
    line-height: 1.3;
    border-radius: 3px;
    color: #fff;
    border: 1px solid #3a87ad; /* default BORDER color */
    background-color: #3a87ad; /* default BACKGROUND color */
    margin: 1px 2px 0; /* spacing between events and edges */
    padding: 0 1px;
}
.fc-time {
  font-weight: bold;
}
.fc-event a {
    color: #fff;
}
.fc-event a:hover,
.fc-event a:focus {
    color: #fff;
}
.fc-event.hebdate, .fc-event.hebdate .fc-event-title,
.fc-event.omer, .fc-event.omer .fc-event-title {
  background-color:#FFF;
  border: 1px solid #FFF;
  color:#999;
}
.fc-event.dafyomi,
.fc-event.dafyomi a,
.fc-event.dafyomi .fc-event-title {
  background-color:#FFF;
  border: 1px solid #FFF;
  color:#08c;
}
.fc-event.dafyomi a:hover,
.fc-event.dafyomi a:focus {
    color: #005580;
}
.fc-event.mishnayomi,
.fc-event.mishnayomi a,
.fc-event.mishnayomi .fc-event-title {
  background-color:#FFF;
  border: 1px solid #FFF;
  color:#257e4a;
}
.fc-event.mishnayomi a:hover,
.fc-event.mishnayomi a:focus {
    color: #15713b;
}

.fc-event.holiday,
.fc-event.holiday .fc-event-title,
.fc-event.holiday.timed,
.fc-event.holiday.timed .fc-event-title {
  background-color:#3a87ad;
  border: 1px solid #3a87ad;
  color:#FFF;
}
.fc-event.fast {
  background-color:#fd7e14;
  border: 1px solid #fd7e14;
  color:#FFF;
}
.fc-event.timed,
.fc-event.timed .fc-event-title,
.fc-event.holiday.timed.fast,
.fc-event.holiday.timed.fast .fc-event-title {
  background-color:#FFF;
  border: 1px solid #FFF;
  color:#333;
}
.fc-event.holiday.yomtov,
.fc-event.holiday.yomtov a,
.fc-event.holiday.yomtov .fc-event-title {
  background-color:#ffd446;
  border: 1px solid #ffd446;
  color:#333;
}
.fc-event.parashat,
.fc-event.parashat .fc-event-title {
  background-color:#257e4a;
  border: 1px solid #257e4a;
  color:#FFF;
}
.fc-event.roshchodesh {
  background-color:#6f42c1;
  border: 1px solid #6f42c1;
  color:#FFF;
}
.fc-event.hebrew .fc-title {
  font-family:'SBL Hebrew',David;
  font-size:115%;
  font-weight:normal;
  direction:rtl;
}
.fc-event.hebrew .fc-time {
  direction:ltr;
  unicode-bidi: bidi-override;
}
.fc-event-time, .fc-event-title {
 padding: 0 1px;
 white-space: normal;
}
.fc .fc-event.fc-event-today .fc-event-title {
  background-color: rgba(255,220,40,0.15);
}

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.

1. Gregorian to Hebrew – single

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

https://www.hebcal.com/converter?cfg=json&date=2011-06-02&g2h=1&strict=1
  • cfg=json – output format is JSON (cfg=json) or XML (cfg=xml)
  • g2h=1 – Convert from Gregorian to Hebrew date
  • date=2011-06-02 – Gregorian date in YYYY-MM-DD format
  • gs=on – After sunset on Gregorian date
  • strict=1 – strict mode will return a 400 Bad Request error for invalid dates

As an alternative to specifying date=YYYY-MM-DD, clients may send gy=YYYY&gm=MM&gd=DD as follows:

  • gy=2011 – Gregorian year
  • gm=6 – Gregorian month (1=January, 12=December). Leading 0 is optional
  • gd=2 – Gregorian day of month. Leading 0 is optional

2. Gregorian to Hebrew – range of dates

To convert a batch of Gregorian dates to Hebrew dates, use this URL format:

https://www.hebcal.com/converter?cfg=json&start=2021-12-29&end=2022-01-04&g2h=1
  • cfg=json – output format is JSON (cfg=json)
  • g2h=1 – Convert from Gregorian to Hebrew date
  • start=2021-12-29 – Gregorian start date in YYYY-MM-DD format
  • end=2022-01-04 – Gregorian end date in YYYY-MM-DD format

Results will be truncated to 180 days if the end date is more than 180 days after the start date.

3. Hebrew to Gregorian – single date

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&strict=1
  • cfg=json – output format is JSON (cfg=json) or XML (cfg=xml)
  • h2g=1 – Convert from Hebrew to Gregorian date
  • hd=25 – Hebrew day of month
  • hy=5749 – Hebrew year
  • hm=Kislev – Hebrew month

Month names may be specified in Hebrew or transliterated as follows:

Month nameHebrewCommon aliases
Nisanניסן
IyyarאיירIyar
Sivanסיון
TamuzתמוזTammuz
Avאב
Elulאלול
Tishreiתשרי
Cheshvanחשון
Kislevכסלו
TevetטבתTeves
ShvatשבטSh'vat
Adarאדר
Adar1אדר א׳Adar 1Adar I
Adar2אדר ב׳Adar 2, Adar II

In leap years, specifying Adar is the same as specifying Adar2. In non-leap years, all three of Adar, Adar1, and Adar2 are considered equivalent and will be interpreted as Adar.

The API is somewhat lenient in what it accepts for Hebrew month names. You can specify sh%27vat or Sh%27vat or Shvat. It will always consistently generate Sh'vat in the response. Generally the API will accept month names with as few as 2 characters, as this is sufficient to disambiguate them from each other,.

Similarly, the API accepts all of Adar1Adar 1Adar IAdar2Adar 2Adar II. Because the capital-i and the lowercase-L look the same in some fonts, we recommend using the numerals 1 and 2 in the API usage. In the generated responses, Hebcal always uses Adar I and Adar II for consistency and compatibility as we’ve done for over 20 years.

4. Hebrew to Gregorian – range of dates

To convert a batch of Hebrew dates to Gregorian dates, use the same URL format as the “Hebrew to Gregorian – single date” above, and add an additional ndays parameter.

https://www.hebcal.com/converter?cfg=json&hy=5749&hm=Kislev&hd=25&h2g=1&ndays=90&strict=1
  • ndays=90 – calculate range of of days (between 2 and 180 inclusive)

5. Other API notes

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

As with all Hebcal.com REST APIs:

  • Both HTTP and HTTPS (HTTP/2) are supported. Although most of the Web has moved to HTTPS, if you wish to reduce CPU overhead on your client you may continue to use plain (port 80) HTTP for API requests
  • We encourage HTTP caching proxies. Proper Cache-Control and Expires are generated in the response
  • We support both gzip and br (brotli) compression; set the appropriate Accept-Encoding header in your request to enable
  • We support HTTP Keep-Alive for multiple requests

6. Sample output in JSON and XML

{
  "gy": 2011,
  "gm": 6,
  "gd": 2,
  "afterSunset": false,
  "hy": 5771,
  "hm": "Iyyar",
  "hd": 29,
  "hebrew": "כ״ט בְּאִיָיר תשע״א",
  "heDateParts": {
    "y": "תשע״א",
    "m": "אייר",
    "d": "כ״ט"
  },
  "events": [
    "Parashat Nasso",
    "44th day of the Omer"
  ]
}
<?xml version="1.0" ?>
<hebcal>
  <gregorian year="2011" month="6" day="2" />
  <hebrew year="5771" month="Iyyar" day="29" str="כ״ט בְּאִיָיר תשע״א" />
</hebcal>

7. Sample output (batch API)

{
  "start": "2021-12-29",
  "end": "2022-01-04",
  "locale": "en",
  "hdates": {
    "2021-12-29": {
      "hy": 5782,
      "hm": "Tevet",
      "hd": 25,
      "hebrew": "כ״ה בְּטֵבֵת תשפ״ב",
      "heDateParts": {
        "y": "תשפ״ב",
        "m": "טבת",
        "d": "כ״ה"
      },
      "events": [
        "Parashat Vaera"
      ]
    },
    "2021-12-30": {
      "hy": 5782,
      "hm": "Tevet",
      "hd": 26,
      "hebrew": "כ״ו בְּטֵבֵת תשפ״ב",
      "heDateParts": {
        "y": "תשפ״ב",
        "m": "טבת",
        "d": "כ״ו"
      },
      "events": [
        "Parashat Vaera"
      ]
    },
    "2021-12-31": {
      "hy": 5782,
      "hm": "Tevet",
      "hd": 27,
      "hebrew": "כ״ז בְּטֵבֵת תשפ״ב",
      "heDateParts": {
        "y": "תשפ״ב",
        "m": "טבת",
        "d": "כ״ז"
      },
      "events": [
        "Parashat Vaera"
      ]
    },
    "2022-01-01": {
      "hy": 5782,
      "hm": "Tevet",
      "hd": 28,
      "hebrew": "כ״ח בְּטֵבֵת תשפ״ב",
      "heDateParts": {
        "y": "תשפ״ב",
        "m": "טבת",
        "d": "כ״ח"
      },
      "events": [
        "Shabbat Mevarchim Chodesh Sh'vat",
        "Parashat Vaera"
      ]
    },
    "2022-01-02": {
      "hy": 5782,
      "hm": "Tevet",
      "hd": 29,
      "hebrew": "כ״ט בְּטֵבֵת תשפ״ב",
      "heDateParts": {
        "y": "תשפ״ב",
        "m": "טבת",
        "d": "כ״ט"
      },
      "events": [
        "Parashat Bo"
      ]
    },
    "2022-01-03": {
      "hy": 5782,
      "hm": "Sh'vat",
      "hd": 1,
      "hebrew": "א׳ בִּשְׁבָט תשפ״ב",
      "heDateParts": {
        "y": "תשפ״ב",
        "m": "שבט",
        "d": "א׳"
      },
      "events": [
        "Rosh Chodesh Sh'vat",
        "Parashat Bo"
      ]
    },
    "2022-01-04": {
      "hy": 5782,
      "hm": "Sh'vat",
      "hd": 2,
      "hebrew": "ב׳ בִּשְׁבָט תשפ״ב",
      "heDateParts": {
        "y": "תשפ״ב",
        "m": "שבט",
        "d": "ב׳"
      },
      "events": [
        "Parashat Bo"
      ]
    }
  }
}