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 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) – 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"
}
]
}