We offer a simple API for looking up this week’s Shabbat times and Torah Portion. This API generates results for a given location on a rolling weekly time window. Weekly calculations change every Sunday at midnight in the city’s local time zone.
This API uses a similar URL and response format as our full Jewish calendar REST API, but offers less control over the dates and times. If you find you want more fine-grained control over the date ranges, or what kinds of events are included and which are excluded, we recommend using the full Jewish calendar REST API instead.
URL Format
The basic URL format is as follows:
https://www.hebcal.com/shabbat?cfg=json&geonameid=3448439&M=on
API Parameters
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
- leyning=off – include Torah and Haftarah for regular Shabbat (default on)
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.
Location parameter
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.
Event title 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.
Results
The returned JSON results includes a list of items that have a category will typically include each of the following:
candles– Candle-lighting on Friday or erev chagparashat– Parashat HaShavua, the weekly Torah portionhavdalah– Havdalah, the end of Shabbat
Depending on the week of the year, other items may appear in the results, including
holiday(withsubcat majororminororfast)zmanim(often withsubcatfastfor “Fast begins” or “Fast ends”)
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
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
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&M=on&lg=s&utm_source=shabbat1c&utm_medium=rss</link>
<atom:link href="https://www.hebcal.com/shabbat?cfg=r&geonameid=3448439&M=on&lg=s&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&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&M=on&lg=s&dt=2015-02-20&utm_source=shabbat1c&utm_medium=rss#20150220-candle-lighting</link>
<guid isPermaLink="false">https://www.hebcal.com/shabbat?geonameid=3448439&M=on&lg=s&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&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&M=on&lg=s&dt=2015-02-21&utm_source=shabbat1c&utm_medium=rss#20150221-havdalah</link>
<guid isPermaLink="false">https://www.hebcal.com/shabbat?geonameid=3448439&M=on&lg=s&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>