SDKs overview

Hebrew Calendar provides a developer API that enables integration of Jewish calendar functionality into various applications. This includes converting dates between the Gregorian and Hebrew calendars, retrieving Jewish holiday information, and calculating Shabbat and holiday candle lighting times. The API supports data exchange in JSON and XML formats, offering flexibility for different development environments and use cases. While the Hebrew Calendar project primarily offers direct API access, specific client libraries are available to streamline development in popular programming languages.

The developer experience is supported by detailed documentation that includes code examples to assist developers in implementing the API across different platforms. This documentation covers various endpoints, such as the Hebrew Date Converter API, the Holiday & Shabbat Times API, and the Geographic Lookup API, each designed for specific calendar-related tasks. These resources are designed to help developers integrate Jewish calendar data efficiently, whether for web applications, mobile apps, or other software solutions.

Official SDKs by language

The Hebrew Calendar project maintains an official JavaScript SDK to facilitate client-side and Node.js integrations. This SDK simplifies interactions with the Hebcal API, abstracting HTTP requests and parsing responses into usable data structures. Developers can leverage this library to incorporate features such as date conversion, holiday listings, and Zmanim (specific times for Jewish observances) directly into their applications.

While JavaScript is the officially supported SDK language, the Hebcal API documentation provides extensive code examples and guidance for other languages like Python, PHP, and Ruby. These examples demonstrate how to make direct HTTP requests to the API endpoints and process the JSON or XML responses. This approach allows developers to use their preferred programming language for integration, even without a dedicated official SDK for every language.

Below is a table summarizing the official SDKs:

Language Package/Module Installation Command Maturity
JavaScript hebcal npm install hebcal Stable

Installation

For JavaScript developers, the official hebcal library is available through npm, the Node.js package manager. This library can be installed in both Node.js projects and front-end web applications that use a module bundler like Webpack or Rollup.

JavaScript (npm)

To install the hebcal library, open your project's terminal and run the following command:

npm install hebcal

After installation, you can import the library into your JavaScript files:

import { HDate, HebrewDate, get \{holidays\}, Location } from 'hebcal';

For web applications, the library can also be included directly via a CDN, though using npm is recommended for modern development workflows and dependency management.

Other Languages (Direct API Calls)

For languages like Python, PHP, and Ruby, where no official SDK is provided, integration involves making direct HTTP requests to the Hebcal API endpoints. This typically requires using a standard HTTP client library available in the respective language. For example, Python developers might use the requests library, while PHP developers might use Guzzle or the built-in curl functions.

Python Example (using requests)

First, ensure you have the requests library installed:

pip install requests

Then, you can make API calls:

import requests

def get_holidays_python(year, month):
    url = f"https://www.hebcal.com/hebcal?v=1&cfg=json&year={year}&month={month}&maj=on&min=on"
    response = requests.get(url)
    response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
    data = response.json()
    return data.get('items', [])

holidays_2026_may = get_holidays_python(2026, 5)
for holiday in holidays_2026_may:
    print(f"Holiday: {holiday['title']} on {holiday['date']}")

PHP Example (using file_get_contents or curl)

Using file_get_contents for simplicity:

<?php
function getHolidaysPHP($year, $month) {
    $url = "https://www.hebcal.com/hebcal?v=1&cfg=json&year={$year}&month={$month}&maj=on&min=on";
    $json = file_get_contents($url);
    if ($json === FALSE) {
        // Handle error
        return [];
    }
    $data = json_decode($json, true);
    return $data['items'] ?? [];
}

$holidays_2026_may = getHolidaysPHP(2026, 5);
foreach ($holidays_2026_may as $holiday) {
    echo "Holiday: " . $holiday['title'] . " on " . $holiday['date'] . "<br>\n";
}
?>

Quickstart example

This quickstart demonstrates how to use the official JavaScript hebcal library to get Jewish holidays for a specific month and convert a Gregorian date to a Hebrew date. This example is suitable for both Node.js environments and modern browser applications.

JavaScript Quickstart (using hebcal npm package)

First, ensure the hebcal package is installed:

npm install hebcal

Then, create a JavaScript file (e.g., app.js) and add the following code:

import { HDate, HebrewDate, getHolidays, Location } from 'hebcal';

// 1. Get Jewish holidays for a specific Gregorian month and year
async function fetchHolidays(year, month) {
  try {
    // The getHolidays function can fetch holidays based on Gregorian date ranges
    // For a specific month, we define a start and end date.
    const startDate = new Date(year, month - 1, 1); // month is 0-indexed in JS Date
    const endDate = new Date(year, month, 0); // Last day of the month

    const holidays = await getHolidays({
      start: startDate,
      end: endDate,
      // You can specify locations for candle lighting times, e.g., 'Jerusalem'
      // location: Location.lookup('Jerusalem'),
      // Additional options like major holidays only or minor holidays
      maj: true, // Include major holidays
      min: true, // Include minor holidays
      mf: true, // Include Rosh Chodesh
      // etc.
    });

    console.log(`Jewish Holidays for ${new Date(year, month - 1).toLocaleString('en-US', { month: 'long', year: 'numeric' })}:`);
    holidays.forEach(holiday => {
      console.log(`- ${holiday.date.toLocaleDateString('en-US')} (${holiday.date.format('hdate')}): ${holiday.desc}`);
    });
  } catch (error) {
    console.error('Error fetching holidays:', error);
  }
}

// 2. Convert a Gregorian date to a Hebrew date
function convertGregorianToHebrew(year, month, day) {
  const gregorianDate = new Date(year, month - 1, day); // month is 0-indexed
  const hebrewDate = new HDate(gregorianDate);

  console.log(`\nGregorian Date: ${gregorianDate.toLocaleDateString('en-US')}`);
  console.log(`Hebrew Date: ${hebrewDate.toString()} (${hebrewDate.getFullYear()} ${hebrewDate.getMonthName()} ${hebrewDate.getDate()})`);
}

// Example usage:
const currentYear = 2026;
const currentMonth = 5; // May

fetchHolidays(currentYear, currentMonth);
convertGregorianToHebrew(currentYear, currentMonth, 29); // May 29, 2026

To run this example, save it as app.js and execute it using Node.js:

node app.js

This script will output the Jewish holidays for May 2026 and the Hebrew date corresponding to May 29, 2026.

Community libraries

Beyond the official JavaScript SDK, a vibrant community contributes libraries and tools that interact with the Hebcal API or implement Jewish calendar calculations independently. These community-driven projects often extend functionality, provide wrappers for specific frameworks, or offer implementations in languages not officially supported by Hebcal.

For instance, developers working with Python might find various packages on PyPI that either wrap the Hebcal API or implement the mathematical algorithms for Hebrew date conversions and Zmanim calculations. Similarly, Ruby gems and PHP packages exist that provide similar capabilities. These libraries can offer alternative approaches to integration, sometimes with different feature sets or API designs.

When choosing a community library, it is advisable to evaluate its active maintenance, community support, and alignment with project requirements. Resources like MDN Web Docs on JavaScript Date objects or language-specific package repositories (e.g., PyPI for Python, RubyGems for Ruby) can provide insights into general date and time handling, which is often a prerequisite for understanding and extending calendar functionality. Developers should consult the respective package documentation and community forums for specific usage instructions and support.

Examples of community approaches might include:

  • Python libraries: Packages that provide a Pythonic interface to the Hebcal API, handling JSON parsing and error management.
  • PHP frameworks: Integrations designed for specific PHP frameworks like Laravel or Symfony, offering service providers or facades for Hebrew calendar data.
  • Ruby gems: Libraries that calculate Jewish calendar events or convert dates, potentially leveraging the Hebcal API or implementing the calendar algorithms directly.

These community efforts broaden the accessibility of Hebrew calendar data and calculations across a wider range of development environments and preferences.