The Jewish holidays, as JSON.

A free, no-authentication REST API for Jewish holiday dates and workday-off calculations — built for HR systems, absence calendars, and anything that plans around the Hebrew calendar. Dates are computed locally from @hebcal/core; no upstream calls.

Overview

Seven read-only endpoints. Responses are cached for one hour (Cache-Control: public, max-age=3600) — holiday dates do not change.

Quickstart

# How many workdays off does 2026 require?
$ curl 'https://whenarethejewishholidays.com/api/v1/workdays?year=2026'

{
  "year": 2026,
  "israel": false,
  "weekend": ["Saturday", "Sunday"],
  "included": ["yomtov"],
  "daysOffRequired": 6,
  "totalObserved": 13,
  "weekdayHolidays": [
    {
      "title": "Pesach I",
      "hebrew": "פֶּסַח א׳",
      "date": "2026-04-02",
      "hebrewDate": "15 Nisan 5786",
      "weekday": "Thursday",
      "category": "yomtov",
      "yomTov": true,
      "about": "Passover, the eight-day festival of freedom…"
    }
  ],
  "weekendHolidays": [ … ]
}

Concepts

Always counted: Yom Tov

Days when work is traditionally prohibited are always part of the workday calculation: Rosh Hashana (2 days), Yom Kippur, Sukkot I–II, Shmini Atzeret, Simchat Torah, Pesach I–II and VII–VIII, and Shavuot I–II. With il=true the one-day Israeli scheme is used.

Optional groups: include

Observance varies by community, so everything else is opt-in via the include parameter:

Weekends

The weekend parameter controls which days don't cost a vacation day: sat-sun (default), fri-sat (Israeli work week), sun, none, or comma-separated day names.

Holidays

$ curl '…/api/v1/holidays?year=2026&categories=yomtov'

$ curl '…/api/v1/holidays/next?after=2026-09-01&count=3'

Workdays

$ curl '…/api/v1/workdays?year=2026&include=cholhamoed,tisha-bav&weekend=fri-sat&il=true'

$ curl '…/api/v1/workdays/compare?from=2026&to=2036'
{ "series": [ { "year": 2026, "daysOffRequired": 6, … }, … ] }

Calendar feed

$ curl -o jewish-holidays.ics '…/api/v1/calendar.ics?from=2026&to=2028&include=cholhamoed'

Reference

Integrating with Workday

Two patterns, depending on how much control you have:

1 · Holiday calendar import (recommended)

1. Download the feed for your policy, e.g. /api/v1/calendar.ics?from=2026&to=2028&include=cholhamoed.
2. In Workday, open Maintain Holiday Calendars and create (or edit) a holiday calendar for the relevant worker population.
3. Add the dates from the feed — each VEVENT is a single all-day holiday with the English name, Hebrew date, and a work-permitted note in the description. (Workday admins typically load these via EIB: export the JSON from /workdays, map date → Holiday Date and title → Holiday Name in the spreadsheet template.)
4. Re-run annually — dates shift against the civil calendar every year.

2 · Absence forecasting via JSON

For staffing models and PTO accrual planning, call /workdays/compare from Workday Studio / Prism (or any middleware) and join daysOffRequired per year against your workforce data. The series is stable and cacheable — fetch it once per year.

Outlook, Google & Apple Calendar

Subscribe (auto-updating): in Google Calendar choose Other calendars → From URL; in Outlook, Add calendar → Subscribe from web; on macOS/iOS, File → New Calendar Subscription. Paste the /calendar.ics URL with your preferred filters.

Import (one-time): download the same URL and import the file.

Errors

Errors are JSON with an error code and human-readable message:

HTTP/1.1 400 Bad Request
{
  "error": "bad_request",
  "message": "Unrecognized include token(s): foo. Valid tokens: cholhamoed, tisha-bav, …"
}