Hebrew Calendar API

Overview

The Hebrew Calendar API provides a programmatic interface for integrating Jewish calendar calculations and data into various applications. It serves developers seeking to display Hebrew dates, identify Jewish holidays, and determine specific religious times like Shabbat and candle-lighting for different locations. The API supports a range of functionalities, including converting dates between the Gregorian and Hebrew calendar systems, retrieving comprehensive holiday information, and performing geographic lookups to calculate local times relevant to Jewish observance.

The primary audience for this API includes developers building educational platforms, community websites, mobile applications for Jewish users, and content management systems that require dynamic display of Jewish chronological data. For example, an application might use the Hebrew Date Converter API to allow users to input a Gregorian date and receive its corresponding Hebrew date, or vice-versa. Similarly, a synagogue's website could integrate the Holiday & Shabbat Times API to automatically display upcoming holidays and local Shabbat candle-lighting and Havdalah times, based on the user's location retrieved via the Geographic Lookup API.

The API is particularly valuable in scenarios where accuracy and adherence to halakhic (Jewish law) principles are critical. It handles the complexities of the lunisolar Hebrew calendar, including leap years and varying start times for days, which begin at sunset. This makes it a suitable tool for personalizing content for Jewish audiences, facilitating event planning around Jewish observances, and developing educational tools that explain the structure and significance of the Hebrew calendar. Its data can be consumed in JSON and XML formats, providing flexibility for integration into diverse tech stacks. The service offers a free tier for personal and non-commercial use, with custom enterprise pricing available for commercial applications requiring higher usage or specialized features.

Key features

• Hebrew Date Converter API: Converts dates between the Gregorian and Hebrew calendar systems, supporting both directions. This allows applications to display dates in a culturally relevant format or to align events across different calendar systems.
• Holiday & Shabbat Times API: Provides data for Jewish holidays, fast days, and specific times such as Shabbat candle-lighting and Havdalah. It includes holiday names, dates, and associated observances, which can be filtered by year or location.
• Geographic Lookup API: Enables calculation of precise times for Shabbat and holidays based on geographical coordinates (latitude and longitude). This is essential for applications requiring localized observance times.
• RSS Feeds: Offers dynamically updated RSS feeds for upcoming Jewish holidays, daily Torah readings, and local Shabbat times, facilitating content syndication.
• iCalendar Feeds: Provides iCalendar (.ics) feeds for integrating Jewish holidays and specific Zmanim (times) into personal calendar applications like Google Calendar or Outlook, supporting subscription-based updates.
• JSON and XML Support: API responses are available in both JSON and XML formats, allowing developers to choose the data representation best suited for their application's parsing needs.
• Multi-Language Examples: Documentation includes code examples in JavaScript, Python, PHP, and Ruby, assisting developers with rapid integration across different programming environments.

Pricing

The Hebrew Calendar API offers a free tier for personal and non-commercial use. Commercial and enterprise applications require custom pricing, which is determined based on specific usage requirements and negotiated directly with the provider. Details regarding specific commercial tiers or usage limits for the free tier are available by contacting the vendor.

Common integrations

• Web Applications: Integrating Hebrew dates and holiday schedules into websites for Jewish organizations, educational institutions, or personal blogs. The JavaScript SDK can facilitate client-side rendering of calendar data.
• Mobile Apps: Developing mobile applications that provide personalized Jewish calendar information, daily Zmanim (times), or holiday reminders.
• Content Management Systems (CMS): Embedding dynamic Jewish calendar content into platforms like WordPress or Drupal to automatically update holiday listings or Torah readings.
• Email Marketing Platforms: Automating personalized email campaigns that acknowledge Jewish holidays or provide timely information based on the Hebrew calendar.
• Event Management Systems: Aligning event schedules with Jewish holidays and observances to avoid conflicts or to highlight relevant dates.
• Smart Home Devices: Developing integrations for voice assistants or smart displays to announce Jewish holidays or Shabbat times based on location.

Alternatives

• Chabad.org Jewish Calendar: Offers a comprehensive online Jewish calendar with holiday information, daily Zmanim, and educational resources.
• MyZmanim: Specializes in providing highly accurate and customizable Zmanim (Jewish prayer times) for various locations worldwide.
• JewishGen Calendar: Provides a date converter and general Jewish calendar information, often used for genealogical research.

Getting started

To begin using the Hebrew Calendar API, developers can access various endpoints to retrieve data in JSON or XML format. The following JavaScript example demonstrates how to fetch upcoming Jewish holidays for a specific location using the API. This example uses the fetch API to make a request and then logs the parsed JSON response to the console. Developers should review the Hebrew Calendar API documentation for full details on available parameters and response structures.

For more advanced usage, such as calculating specific times (Zmanim) or converting dates, additional parameters can be added to the API request. For instance, to get Shabbat times for a specific city, you would include latitude, longitude, and an elevation parameter in your request. The API also supports CORS (Cross-Origin Resource Sharing), allowing direct client-side requests from web applications, which simplifies integration for many front-end projects. When working with calendar data, it is important to handle timezones correctly, as specified in the MDN Web Docs on DateTimeFormat for JavaScript, to ensure accurate display of local times.

async function getUpcomingHolidays(year, month, day, latitude, longitude) {
  const date = new Date(year, month - 1, day);
  const isoDate = date.toISOString().split('T')[0]; // Format as YYYY-MM-DD

  // Example: Get upcoming holidays for a specific location
  // Replace with actual latitude and longitude for desired location
  const url = `https://www.hebcal.com/converter?cfg=json&gy=${year}&gm=${month}&gd=${day}&g2h=1&latitude=${latitude}&longitude=${longitude}`;

  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data = await response.json();
    console.log('Hebrew Date Conversion and Holidays:', data);

    // Example of accessing specific holiday information
    if (data.holidays && data.holidays.length > 0) {
      console.log('Upcoming Holiday:', data.holidays[0].title);
    }

    // Example: Fetching specific holiday data for a year
    const holidaysUrl = `https://www.hebcal.com/holidays?cfg=json&year=${year}&month=${month}&sec=holidays`;
    const holidaysResponse = await fetch(holidaysUrl);
    const holidaysData = await holidaysResponse.json();
    console.log(`Holidays for ${year}:`, holidaysData);

  } catch (error) {
    console.error('Error fetching Hebrew calendar data:', error);
  }
}

// Example usage: Fetch data for today's date in New York City
// May 28, 2026 (Gregorian) corresponds to 11 Sivan 5786 (Hebrew)
getUpcomingHolidays(2026, 5, 28, 40.7128, -74.0060);