Category Archives: Developers, APIs, RSS Feeds, Source Code

The Hebcal website and APIs support 13 different languages for event titles. By default, Hebcal uses Sephardic transliterations. To transliterate event titles in a different language, specify lg=LANG parameter using one of the following values:

For example, depending on which language is selected, the event title “Sukkot” will be transliterated as one of the following:

• Soukkot
• Sucos
• Sucot
• Sukkos
• Sukkot
• Sukot
• Szukkot
• Суккот
• סוּכּוֹת
• סוכות

We are pleased to offer an experimental Zmanim (halachic times) iCalendar feed. Many calendar desktop, mobile or web apps support the iCalendar (.ICS file extension) format.

You can specify your location using a GeoNames.org numeric ID, a United States ZIP code, or a geographic position (location specified by latitude, longitude, and timezone). You’ll find details on how to specify the location parameters on the Zmanim (halachic times) API page.

By default, event titles use a Sephardic transliteration. Append &lg=LANG to the URL to render the events titles using an alternate event language.

Option 1: All zmanim in a single daily untimed event

The basic URL format of the feeds is this:

webcal://download.hebcal.com/zmanim2?geonameid=5368361

The calendar feed will contain zmanim for the next 90 days. There will be a single all-day (untimed) event with the Hebrew date, and the description/notes will contain all times. Here is an example event:

Option 2: Timed events

If you would prefer approximately 20 timed events per day, we offer an alternate feed format using this alternate URL format (note /zmanim instead of /zmanim2 above):

webcal://download.hebcal.com/zmanim?zip=02906

The calendar feed will contain events for the next 60 days. Each event represents only a single halachic time.

Here’s an example of the events included in the calendar feed:

Option 3: Sunrise and Sunset only

An alternate feed which contains only sunrise and sunset events is available using URL format like this (note /sunrs instead of /zmanim2 above):

webcal://download.hebcal.com/sunrs?zip=02906

In this variation, there are only two events per day.

If you’d like to display today’s Omer count on your website and you’re comfortable with a bit of Javascript, you can use a snippet like this:

To display the Omer count in another language, change the &lg=s to another supported language code (for example h for Hebrew, es for Spanish, etc).

If you’d like to display the long omer count in English or Hebrew, you can dislay item.omer.count.en or item.omer.count.he

• he: “הַיוֹם שְׁמוֹנָה עָשָׂר יוֹם, שְׁהֵם שְׁנֵי שָׁבוּעוֹת וְאַרְבָּעָה יָמִים לָעוֹמֶר”,
• en: “Today is 18 days, which is 2 weeks and 4 days of the Omer”

See also item.omer.sefira.he, .en, and .translit.

• he: “נֶּֽצַח שֶׁבְּתִּפאֶרֶת”,
• translit: “Netzach sheb’Tiferet”,
• en: “Eternity within Beauty”

Most Hebcal content is licensed under a Creative Commons Attribution 4.0 International License (sometimes referred to as “CC BY 4.0”). If you use Hebcal.com content or APIs, continue reading to understand what privileges this license grants and how you can give appropriate credit to Hebcal.

The CC BY 4.0 license is designed to encourage use and reuse of content. You can remix, transform, and build upon the material for any purpose, even commercially. You need not ask for permission, notify us about the usage, or send us money. This license gives you permission to freely to copy and redistribute the material in any medium or format as long as you give appropriate credit to Hebcal.com.

Creative Commons licenses have a flexible attribution requirement, so there is not necessarily one correct way to provide attribution. The proper method for giving credit will depend on the medium and means you are using, and may be implemented in any reasonable manner.

On a website, you might include a short piece of text with a link back to Hebcal.com, e.g.:

Powered by Hebcal Shabbat Times

Or you might include the following at the bottom of a printed page or refrigerator magnet:

Jewish holidays and candle-lighting times are provided by Hebcal.com with a CC BY 4.0 International License.

Creative Commons publishes best practices for attribution which includes some good (and not so good) examples of attribution.

We are pleased to offer support for REST API for Torah Reading for full kriyah leyning on Shabbat and holidays, Triennial (optionally) for Shabbat, and weekday readings on Mondays & Thursdays.

Note that this is a web API that provides the same functionality of the getLeyningOnDate API provided by the JavaScript @hebcal/leyning package. If you’re building a JavaScript application, consider using the native JS library instead of web APIs for a faster user experience.

Here’s the basic URL format:

https://www.hebcal.com/leyning?cfg=json&start=2022-09-21&end=2022-09-26

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

Parameters and their meanings

• cfg=json – output JSON. Required
• For a single date:
  • date=2011-06-02 – Gregorian date in YYYY-MM-DD format
• Or, for a date range:
  • start=2021-01-15 – start date using YYYY-MM-DD format
  • end=2021-01-22 – end date using YYYY-MM-DD format
  • Results will be truncated to 180 days if the end date is more than 180 days after the start date
• Diaspora vs. Israel
  • i=off – Diaspora holidays and Torah readings (default if unspecified)
  • i=on – Israel holidays and Torah readings
• triennial=off – reduce size of JSON response payload by disabling Triennial aliyot details (default on)

Example output

{
  "date": "2022-10-03T18:41:57.168Z",
  "location": "Diaspora",
  "range": {
    "start": "2022-09-21",
    "end": "2022-09-26"
  },
  "items": [
    {
      "date": "2022-09-22",
      "hdate": "26 Elul 5782",
      "name": {
        "en": "Nitzavim",
        "he": "נִצָּבִים"
      },
      "parshaNum": 51,
      "weekday": {
        "1": {"k": "Deuteronomy", "b": "29:9", "e": "29:11", "v": 3},
        "2": {"k": "Deuteronomy", "b": "29:12", "e": "29:14", "v": 3},
        "3": {"k": "Deuteronomy", "b": "29:15", "e": "29:28", "v": 14}
      }
    },
    {
      "date": "2022-09-24",
      "hdate": "28 Elul 5782",
      "name": {
        "en": "Nitzavim",
        "he": "נִצָּבִים"
      },
      "parshaNum": 51,
      "summary": "Deuteronomy 29:9-30:20",
      "fullkriyah": {
        "1": {"k": "Deuteronomy", "b": "29:9", "e": "29:11", "v": 3},
        "2": {"k": "Deuteronomy", "b": "29:12", "e": "29:14", "v": 3},
        "3": {"k": "Deuteronomy", "b": "29:15", "e": "29:28", "v": 14},
        "4": {"k": "Deuteronomy", "b": "30:1", "e": "30:6", "v": 6},
        "5": {"k": "Deuteronomy", "b": "30:7", "e": "30:10", "v": 4},
        "6": {"k": "Deuteronomy", "b": "30:11", "e": "30:14", "v": 4},
        "7": {"k": "Deuteronomy", "b": "30:15", "e": "30:20", "v": 6},
        "M": {"k": "Deuteronomy", "b": "30:15", "e": "30:20", "v": 6}
      },
      "haft": {"k": "Isaiah", "b": "61:10", "e": "63:9", "v": 23},
      "haftara": "Isaiah 61:10-63:9",
      "triennial": {
        "1": {"k": "Deuteronomy", "b": "29:9", "e": "29:11", "v": 3},
        "2": {"k": "Deuteronomy", "b": "29:12", "e": "29:14", "v": 3},
        "3": {"k": "Deuteronomy", "b": "29:15", "e": "29:28", "v": 14},
        "4": {"k": "Deuteronomy", "b": "30:1", "e": "30:6", "v": 6},
        "5": {"k": "Deuteronomy", "b": "30:7", "e": "30:10", "v": 4},
        "6": {"k": "Deuteronomy", "b": "30:11", "e": "30:14", "v": 4},
        "7": {"k": "Deuteronomy", "b": "30:15", "e": "30:20", "v": 6},
        "M": {"k": "Deuteronomy", "b": "30:15", "e": "30:20", "v": 6}
      },
      "triYear": 3,
      "triHaftara": "Isaiah 65:16-25",
      "triHaft": {"k": "Isaiah", "b": "65:16", "e": "65:25", "note": "terem yikrau ani e'eneh", "v": 10}
    },
    {
      "date": "2022-09-26",
      "hdate": "1 Tishrei 5783",
      "name": {
        "en": "Rosh Hashana I",
        "he": "רֹאשׁ הַשָּׁנָה א׳"
      },
      "fullkriyah": {
        "1": {"p": 4, "k": "Genesis", "b": "21:1", "e": "21:4", "v": 4},
        "2": {"p": 4, "k": "Genesis", "b": "21:5", "e": "21:12", "v": 8},
        "3": {"p": 4, "k": "Genesis", "b": "21:13", "e": "21:21", "v": 9},
        "4": {"p": 4, "k": "Genesis", "b": "21:22", "e": "21:27", "v": 6},
        "5": {"p": 4, "k": "Genesis", "b": "21:28", "e": "21:34", "v": 7},
        "M": {"p": 41, "k": "Numbers", "b": "29:1", "e": "29:6", "v": 6}
      },
      "summary": "Genesis 21:1-34; Numbers 29:1-6",
      "summaryParts": [
        {"k": "Genesis", "b": "21:1", "e": "21:34"},
        {"k": "Numbers", "b": "29:1", "e": "29:6"}
      ],
      "haft": {"k": "I Samuel", "b": "1:1", "e": "2:10", "v": 38},
      "haftara": "I Samuel 1:1-2:10"
    }
  ]
}