Is there a free API for Jewish holidays and Shabbat times?

Yes - Hebcal exposes the Hebrew calendar, holidays and candle-lighting times as JSON with no authentication required, plus npm packages including @hebcal/core for local computation. The content is licensed Creative Commons Attribution 4.0, so attribution is required if you display the data to end users.

Why does my booking system still allow appointments on a holiday eve?

Because a day in the Hebrew calendar begins at sunset, so a holiday actually starts the evening before its calendar date. A system that blocks only the date itself still offers late-afternoon appointments on the day the business is already closing. Block from a point in the preceding evening, and treat the festival eve as shortened hours rather than either open or closed.

Does the Jewish holiday calendar differ in Israel?

Yes - some festivals run an extra day outside Israel. Hebcal has an option determining which schedule to use, and if you do not set it you get the Diaspora calendar, which blocks a day when an Israeli business is actually open. Customers then cannot book for no reason, and nobody reports it as a bug. Set the option explicitly rather than relying on a default.

Can I just use a fixed Friday closing time?

No, because Shabbat start times vary through the year - in Israel the summer-to-winter difference is hours - and they vary by city. A fixed 3pm closing wastes trading hours in summer and is too late in winter. Fetch candle-lighting times for the business's actual location, and keep the margin before them as a configurable parameter.

Should a booking system call a holiday API on every availability check?

No. The Hebrew calendar is deterministic - computed rather than published - so it will not change. Fetch a year ahead, cache it locally, refresh on a monthly schedule rather than in a user request, and precompute the blocked windows. That removes latency from availability checks and means an external outage does not stop bookings.

Jewish Holidays API for Scheduling

Hebcal gives you Jewish holidays, Shabbat times and the Hebrew calendar as JSON with no authentication. The hard part is not fetching it - it is that a holiday starts the evening before, which most systems block a day too late.

Any system booking appointments in Israel needs to know when it cannot. Hebcal exposes the Hebrew calendar, holidays and Shabbat times as JSON, with no authentication - so the technical part is an hour. What takes time is that the mental model of "a holiday is a day" is simply wrong, and most systems are built on it.

What Hebcal provides

There is a REST API returning JSON, plus npm packages - @hebcal/core for local computation and @hebcal/rest-api for exports. Coverage includes holidays, candle-lighting and havdalah times by location, Hebrew-to-Gregorian conversion, the weekly Torah portion and the counting of the Omer.

Two practical points:

No authentication. No API key, no registration. That simplifies setup considerably.
The licence is Creative Commons Attribution 4.0 - meaning attribution is required. If you display the data to end users, it is worth checking what that means in your product. Not a heavy burden, but a real obligation rather than a footnote.

Take the exact request shape and parameters from the official documentation at hebcal.github.io/api/.

The bug almost every system has: the evening before

This is the most important point in the article.

A day in the Hebrew calendar begins at sunset, not at midnight. Which means a holiday appearing on a given calendar date starts the evening before.

The practical consequence: a system blocking only the holiday date will still offer a 4pm appointment the evening before - precisely the hours when the business has already closed. The customer receives a confirmation, arrives, and finds a locked door.

And it looks like a random bug, because for most of the year the system works perfectly.

What is needed: block from a point in the evening before the holiday, not from the start of the date. And an eve of a festival is itself usually a shortened working day rather than a closed one - so do not block it entirely, shorten its hours.

The same logic applies to Shabbat: it begins on Friday evening, not on Saturday morning.

Israel is not the Diaspora

The second trap, and very easy to miss: the holiday schedule in Israel differs from the Diaspora's. Some festivals run an additional day outside Israel.

Hebcal has an option determining which schedule to use. If you do not set it, you get the Diaspora calendar - and block a day on which the Israeli business is in fact open. Customers cannot book for no reason, and nobody will report it as a bug.

Check the exact parameter name in the documentation and set it explicitly. Do not rely on a default.

Shabbat times move

The third common mistake is fixing a Friday closing time - 3pm, say - and assuming it covers everything.

It does not: Shabbat start time varies through the year, and in Israel the summer-to-winter gap is hours. Closing at 3pm in summer wastes trading hours; the same closing time in winter is after the fact.

And it varies by city. Hebcal returns candle-lighting and havdalah times by location, so it is worth fetching them for the city the business operates in rather than using a generic value.

A design point: candle-lighting time is not closing time. A business needs a margin before it - that is a business setting which should be a parameter, not a constant in code.

Architecture: cache, not live calls

The temptation is to call the API on every availability check. Do not.

The Hebrew calendar is deterministic - it is computed, not published, and it will not change. There is no reason to call an external service every time someone opens the booking window.

The correct pattern:

Fetch a year ahead and store locally.
Refresh monthly in a scheduled job, not in a user request.
Precompute the list of blocked windows - including festival eves and Shabbat - rather than calculating live.

The benefits: no latency on an availability check, and if Hebcal is unavailable your system keeps working. An external service in the critical path of booking an appointment is an avoidable point of failure.

A further option: @hebcal/core computes locally, meaning the external call can be dropped entirely.

What the system still needs from the business

The API gives you the calendar. It does not know how this particular business operates. Three questions requiring the client's answer rather than the code's:

What happens on a festival eve? Closed, or shortened hours - and until when.
What margin before Shabbat begins? An hour? Two?
Which holidays are even relevant? Not every business closes during intermediate festival days, and not every business is open. That is a business decision, and sometimes it differs by branch.

Worth holding as a setting in an admin interface so the business can change it themselves. Otherwise every policy change is a call to the developer.

What breaks in practice

Time zones. If the server is on UTC and the business is in Israel, computing "today" can land on the wrong date around midnight. Work in the business's time zone and convert for storage - exactly the pattern required in any booking system.
Existing appointments. When a block is added, what happens to appointments already made in that window? Do not delete silently - alert the operator.
Hebrew in PDFs and email. A Hebrew holiday name inside a booking confirmation is mixed text, and that is where directionality breaks.

Checklist

Set the Israel option explicitly - do not rely on a default.
Block from the evening before, not from the start of the date.
Fetch Shabbat times for the business's location, not a fixed value.
Margin before Shabbat as a parameter, not in code.
Cache a year ahead; refresh on a schedule, not in a request.
Test what happens to existing appointments when a block is added.
Check the licence's attribution requirement against how you display the data.

Jewish Holidays in a Booking System: The API and the Evening-Before Bug

Key takeaways