n8n-nodes-shabbat-time
Version:
n8n community node to check if a given date/time falls on Shabbat or Jewish holiday with precise time checking
200 lines (155 loc) • 6.22 kB
Markdown
# 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](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.
```bash
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
```javascript
// Input: Friday, December 13, 2024 (any time)
// Check Exact Time: false
// Output: true (because it's Erev Shabbat)
```
### Precise Time Check
```javascript
// 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
```json
{
"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](https://www.hebcal.com/home/developer-apis).
## Compatibility
- n8n version: 1.0.0 or later
- Node.js version: 20.15 or later
## License
[MIT](LICENSE.md)
## Credits
- Powered by [Hebcal.com](https://www.hebcal.com/) API
- Jewish calendar calculations by Hebcal
## Support
For issues and feature requests, please visit the [GitHub repository](https://github.com/idobe977/n8n-nodes-shabbat-time).
## Contributing
Contributions are welcome! Please read the contributing guidelines and submit pull requests.