- General
-
Questions
Multiple issues regarding the Shabbat Rest API
1. I was surprised to discover that the API returns way more info than the Candle Lighting and Havdalah dates - I managed to extract these dates by iterating through the items array and checking the title_orig field, but is this the intended way?
2. Is there a way to know the next Shabbat info on Saturday? I attempted around 10 PM but got the current info.
Answer
Weekly calculations change every Sunday at midnight in the city’s local time zone.
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”)
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.
Hello, thank you for responding.
- So if I understand you correctly, on Saturday I need to wait until 00:00(Start of Sunday) and then query the API?
Would it be safer to wait an extra minute just to verify I get the next Shabbat info? - By "typically" do you mean definitely? This is why I asked what the intended way is.
For now I've changed my code to match against the category, but I'd be glad if you could clarify.
Regarding the full API, it similarly returned data I didn't ask for even after experimenting with the docs.
In my humble opinion the docs are confusing; But since I managed to get what I needed, There's no need dive into that here.
If you don't want to wait until Saturday at midnight local time, you can always specify an exact date. The documentation describes this as follows:
You can optionally specify an exact date, for example 13 February 2021. If unspecified, defaults to today.
- gy=2021&gm=2&gd=13
Typically doesn't mean definitely. If the Shabbat is not a regular parsha because it's a holiday instead, you will not find a parashat category present.
Sorry the docs are confusing!
Thanks a lot! Just to be extra safe, can you confirm that this workflow always achieves the next Shabbat dates?
- Get the current date. If it's Saturday, increase the day of month by 1.
- Query the Shabbat API along with the adjusted date.
- Extract the entrance and end dates by the candles and havdalah fields respectively
That strategy would work almost all of the time, but not quite all of the time.
For example, on Friday September 11, 2026 is Erev Rosh Hashana. You'll have a candles event that day.
Saturday, September 12, 2025 is Rosh Hashana 5787 and that evening is the 2nd erev. Although it's Saturday night, there will NOT be a havdalah event. Instead, you will have yet another candles event on Saturday night. (and then you'll have a havdalah event on Sunday night September 13 when the 2nd day of RH concludes.
I see, I would've never thought about such edge cases myself!
What do you think about searching the earliest candles item(which falls on Friday), and then approximating the Havdalah date myself by using the next day with the havdalah item's time?
Also regarding the provided urls, the docs have nothing about the "zip" parameter. What does it do?
Most of the advanced REST APIs allow the client to specify a desired location using GeoNames.org numeric ID, United States ZIP code, or latitude/longitude. See the location API page for further details on how to enable/disable the optional elevation for sunset calculation.
Here is how you'd do a Friday - Sunday using the Jewish calendar API
And here is the equivalent using the Shabbat API
https://www.hebcal.com/shabbat?cfg=json&zip=90210&gy=2026&gm=9&gd=11&leyning=off
The results are nearly identical. You can specify an end date using the Jewish calendar API but you cannot with the Shabbat API.
As we mentioned before, the Jewish calendar API also gives you a bit more control. In the example above, you will note that the Jewish calendar API doesn't display fast times or minor/modern holidays (because we didn't set those URL parameters to on).
Customer support service by UserEcho
Weekly calculations change every Sunday at midnight in the city’s local time zone.
The returned JSON results includes a list of
items that have acategorywill typically include each of the following:candles– Candle-lighting on Friday or erev chagparashat– Parashat HaShavua, the weekly Torah portionhavdalah– Havdalah, the end of ShabbatDepending 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”)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.