n8n-nodes-shabbat-time

An advanced n8n community node to check if a given date/time falls on Shabbat or Jewish holiday using the Hebcal API with precise time checking capabilities.

Installation

Follow the installation guide in the n8n community nodes documentation.

npm install n8n-nodes-shabbat-time

Features

• ✅ Check if a specific date falls on Shabbat
• ✅ Check if a specific date falls on Jewish holidays (major and minor)
• ✅ NEW Precise time checking for Shabbat entry/exit times
• ✅ NEW Support for Chol Hamoed (intermediate festival days)
• ✅ Support for multiple location formats (GeoNames ID, coordinates, ZIP code)
• ✅ Default location: Tel Aviv, Israel
• ✅ Configurable candle lighting time
• ✅ Israel holiday schedule (not Diaspora)
• ✅ Detailed information about Jewish events and times
• ✅ Usable as AI Tool in n8n agents

Operations

Check Date

Checks if a given date/time falls on Shabbat or Jewish holiday.

Input Parameters:

• Date: The date/time to check (date/time picker)
• Location Type: Choose between GeoNames ID, coordinates, or ZIP code
• GeoNames ID: Numeric ID from GeoNames.org (default: 293397 for Tel Aviv)
• Latitude/Longitude: Geographic coordinates (default: Tel Aviv)
• ZIP Code: US ZIP code for location
• Include Minor Holidays: Whether to include minor holidays like Rosh Chodesh
• Include Chol Hamoed: Whether to include intermediate festival days
• Check Exact Time: Enable precise time checking for Shabbat entry/exit
• Candle Lighting Minutes: Minutes before sunset for candle lighting (default: 18)

Time Checking Logic

Date-Only Mode (Check Exact Time = false)

Returns true if the given date falls on Shabbat or a holiday, regardless of time.

Precise Time Mode (Check Exact Time = true)

Returns true only if the exact date/time falls within Shabbat or holiday period:

Example for Friday-Saturday Shabbat:

• Friday 19:59 (before candle lighting at 20:00) → false
• Friday 20:00 (candle lighting) → true
• Saturday morning → true
• Saturday 21:30 (after Havdalah at 21:15) → false

Output:

• isShabbatOrHoliday: Boolean indicating if the date/time is Shabbat or holiday
• inputDate: The original input date
• formattedDate: Date in YYYY-MM-DD format
• dayOfWeek: Day of the week in English
• checkExactTime: Whether exact time checking was enabled
• categories: Array of event categories found for this date
• details: Detailed information about events on this date
• location: Location information from Hebcal
• sabbatTimes: Object with candle lighting and Havdalah times
• settings: Configuration used for this check

Usage Examples

Basic Date Check

// Input: Friday, December 13, 2024 (any time)
// Check Exact Time: false
// Output: true (because it's Erev Shabbat)

Precise Time Check

// Input: Friday, December 13, 2024 19:45
// Check Exact Time: true
// Candle lighting: 20:00
// Output: false (before Shabbat starts)

// Input: Friday, December 13, 2024 20:15
// Check Exact Time: true  
// Output: true (Shabbat has started)

Example Output

{
  "isShabbatOrHoliday": true,
  "inputDate": "2024-12-13T20:15:00.000Z",
  "formattedDate": "2024-12-13",
  "dayOfWeek": "Friday",
  "checkExactTime": true,
  "categories": ["candles", "parashat"],
  "sabbatTimes": {
    "candleLighting": "2024-12-13T18:00:00+02:00",
    "havdalah": "2024-12-14T19:15:00+02:00",
    "isInShabbatTimeRange": true
  },
  "details": [
    {
      "title": "Candle lighting: 6:00pm",
      "category": "candles",
      "hebrew": "הדלקת נרות",
      "date": "2024-12-13T18:00:00+02:00"
    }
  ],
  "location": {
    "title": "Tel Aviv, Tel Aviv, Israel",
    "city": "Tel Aviv",
    "tzid": "Asia/Jerusalem"
  },
  "settings": {
    "includeMinorHolidays": true,
    "includeCholHamoed": false,
    "checkExactTime": true,
    "candleLightingMinutes": 18,
    "location": "geonameid"
  }
}

Categories Detected

The node detects the following categories:

• candles - Candle lighting (Friday evening or holiday eve)
• havdalah - Havdalah (end of Shabbat)
• parashat - Weekly Torah portion (Shabbat)
• holiday - Jewish holidays (major)
• roshchodesh - Rosh Chodesh (if minor holidays enabled)
• fast - Fast days (if minor holidays enabled)
• modern - Modern holidays including Chol Hamoed (if enabled)

Location Options

GeoNames ID (Recommended)

Use the numeric ID from GeoNames.org for precise location data.

Common GeoNames IDs:

• Tel Aviv: 293397 (default)
• Jerusalem: 281184
• Haifa: 294801
• New York: 5128581
• London: 2643743
• Los Angeles: 5368361

Coordinates

Provide latitude and longitude for any location worldwide.

ZIP Code

Use US ZIP codes for locations within the United States.

Version 2.0.0 Changes

🚀 Major New Features:

• Precise Time Checking: Check exact time for Shabbat entry/exit
• Chol Hamoed Support: Optional inclusion of intermediate festival days
• Enhanced API: Now uses full Hebcal calendar API
• Israel Schedule: Uses Israel holiday schedule by default
• Improved Output: Detailed sabbath times and configuration info

🔧 Improvements:

• Default location changed to Tel Aviv
• Better error handling and validation
• More detailed event information
• Optimized API calls with date ranges

API Reference

This node uses the Hebcal Jewish Calendar REST API.

Compatibility

• n8n version: 1.0.0 or later
• Node.js version: 20.15 or later

License

MIT

Credits

• Powered by Hebcal.com API
• Jewish calendar calculations by Hebcal

Support

For issues and feature requests, please visit the GitHub repository.

Contributing

Contributions are welcome! Please read the contributing guidelines and submit pull requests.