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