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
API Parameters
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 integrationcfg=rss for RSS (Atom 1.0)cfg=ics for iCalendar RFC 5545cfg=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) – defaultyt=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.)ny=1 – number of years override (default 1)
start=2021-12-29 – Gregorian start date in YYYY-MM-DD formatend=2022-01-04 – Gregorian end date in YYYY-MM-DD format
Event options
All booleans, default off. To enable, specify either on (case-sensitive) or 1.
maj=on – Major holidays
yto=on – Yom Tov only; suppresses all other event options
min=on – Minor holidays (Tu BiShvat, Lag B’Omer, …)nx=on – Rosh Chodeshmf=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 leyning=on when s=on)
D=on – Hebrew date for dates with some eventd=on – Hebrew date for entire date rangeo=on – Days of the Omerykk=on – Yom Kippur Katan
Daily Learning options
All booleans, default off. To enable, specify either on (case-sensitive) or 1.
F=on – Daf Yomimyomi=on – Mishna Yominyomi=on – Nach Yomidty=on – Tanakh Yomidps=on – Daily Tehillim (Psalms)dcc=on – Sefer Chofetz Chaimdshl=on – Shemirat HaLashondr1=on – Daily Rambamyyomi=on – Yerushalmi Yomidw=on – Daf-a-Week
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
For more information What is the differerence between the Diaspora and Israeli sedra schemes?
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=40M=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
Specify the desired location using GeoNames.org numeric ID, United States ZIP code, or latitude/longitude. This page also describes how to enable/disable the optional elevation for sunset calculation.
Language
By default, event titles use a Sephardic transliteration. Append &lg=LANG to the URL to render the events titles using an alternate event language.
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 (_).
Licensing
Content generated by the Hebcal.com web APIs is licensed under a Creative Commons Attribution 4.0 International License. This means that you can use you are free to copy and redistribute the material in any medium or format as long as you give appropriate credit to Hebcal.com.
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"
}
]
}
