Hebrew Calendar Getting Started: Integration & API Keys (2026)

Getting started overview

Getting started with the Hebrew Calendar API involves a sequence of steps designed to enable developers to quickly integrate Jewish calendar functionality into their applications. The process generally begins with familiarizing oneself with the API's capabilities and terms of use, particularly regarding the free tier for personal and non-commercial projects. This initial phase defines the scope of usage and any potential requirements for commercial licensing.

Following this, developers focus on setting up their environment, which typically includes obtaining an API key. This key is essential for authenticating requests and accessing the various endpoints offered by the Hebrew Calendar API, such as those for date conversions, holiday lookups, and Shabbat times. The platform supports multiple response formats, including JSON and XML, providing flexibility for different integration patterns.

The final step in getting started is making a first successful API call. This serves as a critical confirmation that the API key is valid, the network configuration is correct, and the developer's understanding of the API's request and response structure is accurate. Many developers opt for a simple endpoint, like a date conversion, for this initial test to minimize complexity and focus on connectivity.

The following table provides a quick reference for the getting started process:

Create an account and get keys

The Hebrew Calendar API operates on a free-tier model for personal and non-commercial use, which simplifies the initial setup process as it does not generally require a formal account creation with a login and password for basic access. Instead, the API often uses a more direct access method where the API key is implicitly part of the endpoint URL for non-commercial use, or specific parameters might function as a form of identification. For commercial or enterprise use, custom pricing and arrangements are necessary, which would likely involve a formal account setup and explicit API key management.

For personal and non-commercial projects, an API key, if explicitly required, is typically obtained by consulting the Hebrew Calendar developer documentation. The documentation details how to construct valid API requests, which often include parameters that serve to identify the user or application. This approach distinguishes it from APIs that rely on a dedicated developer portal for key generation and management, such as those described in Google Cloud's API key documentation.

To determine if an explicit key is needed for your specific use case, and how to obtain or use it, always refer directly to the official Hebrew Calendar developer API home page. The documentation provides example URLs and parameters, which implicitly or explicitly contain any required identifiers for making a valid request under the free tier. For commercial licensing inquiries, the website generally directs users to contact them directly for custom enterprise pricing and specific API access terms.

Your first request

Making your first request to the Hebrew Calendar API is a crucial step to confirm your setup and understanding of the API structure. A common starting point is the Hebrew Date Converter API, as it is straightforward and demonstrates basic functionality. This API allows you to convert a Gregorian date to a Hebrew date or vice versa, and requires minimal parameters.

The Hebrew Calendar API supports JSON and XML response formats. For most modern applications, JSON is preferred due to its lightweight nature and ease of parsing. You will typically send a GET request to a specific URL, including any necessary query parameters.

Example: Converting a Gregorian date to a Hebrew date

To convert a Gregorian date (e.g., May 29, 2026) to its Hebrew equivalent, you would use an endpoint similar to the following. Note that for non-commercial use, an explicit API key in the header or a dedicated parameter might not be required, as the URL structure itself often embeds the necessary identifiers or operates on an open basis for basic requests.

Request structure (HTTP GET)

GET https://www.hebcal.com/converter?cfg=json&gy=2026&gm=5&gd=29&g2h=1 HTTP/1.1
Host: www.hebcal.com

In this example:

• cfg=json specifies that the response format should be JSON.
• gy=2026 sets the Gregorian year to 2026.
• gm=5 sets the Gregorian month to May.
• gd=29 sets the Gregorian day to 29.
• g2h=1 instructs the API to convert a Gregorian date to a Hebrew date.

Expected JSON response

A successful response would return a JSON object containing the converted date and related information. The exact structure may vary slightly, but it will generally include elements like the Hebrew date, day of the week, and perhaps related holidays or fasts.

{
  "gy": 2026,
  "gm": 5,
  "gd": 29,
  "hy": 5786,
  "hm": "Sivan",
  "hd": 3,
  "hebrew": "3 Sivan 5786",
  "events": [
    {
      "title": "Shabbat Mevarchim Chodesh Sivan",
      "date": "2026-05-30T00:00:00.000Z",
      "category": "parashat"
    },
    {
      "title": "Erev Shavuot",
      "date": "2026-05-31T00:00:00.000Z",
      "category": "holiday"
    }
  ],
  "date": "2026-05-29T00:00:00.000Z"
}

This response confirms that May 29, 2026, corresponds to the 3rd day of Sivan, 5786, and also provides information about upcoming events like Shabbat Mevarchim Chodesh Sivan and Erev Shavuot.

Example using JavaScript (Node.js with node-fetch)

Using a client library like node-fetch for Node.js environments demonstrates how to make this request programmatically:

const fetch = require('node-fetch');

async function convertGregorianToHebrew() {
  const url = 'https://www.hebcal.com/converter?cfg=json&gy=2026&gm=5&gd=29&g2h=1';

  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 Result:', data);
  } catch (error) {
    console.error('Error fetching Hebrew date:', error);
  }
}

convertGregorianToHebrew();

This JavaScript example outlines sending a GET request and handling the JSON response, logging the converted date to the console. Developers can adapt this pattern for other programming languages or environments, referencing the MDN Web Docs on using the Fetch API for browser-based applications.

Common next steps

Once you've successfully made your first API call, you can explore the broader capabilities of the Hebrew Calendar API. Common next steps often involve integrating more complex features or building out specific application functionalities.

• Holiday and Shabbat Times API: This is one of the most frequently used features. You can retrieve lists of holidays, fasts, and candle-lighting times for Shabbat and festivals. This typically requires specifying a geographic location (latitude/longitude or a placename) to get accurate Zmanim (specific times in Jewish law). Examples include fetching Shabbat candle lighting times for a specific city or holidays for a given year. The Holiday & Shabbat Times API documentation provides the necessary parameters and example requests.
• Geographic Lookup API: To get precise Shabbat and holiday times, you might first need to use the Geographic Lookup API. This allows you to search for locations by city name, ZIP code, or coordinates to obtain latitude, longitude, and timezone information, which are crucial for Zmanim calculations. This API is essential for applications that need to dynamically adjust to a user's location.
• iCalendar and RSS Feeds: Beyond direct API calls, Hebrew Calendar also offers iCalendar and RSS feeds. These are useful for integrating dynamic calendar data directly into popular calendar applications (e.g., Google Calendar, Outlook) or news readers, without needing to process raw API responses. The Hebrew Calendar feeds page details how to construct these feed URLs.
• Error Handling and Robustness: Implement comprehensive error handling in your application. This includes checking HTTP status codes, parsing error messages from the API response, and providing informative feedback to users. Consider retries for transient network issues and implement appropriate rate limiting if applicable to avoid exceeding any unstated usage policies.
• SDKs and Libraries: While the Hebrew Calendar API provides direct HTTP access, developers may choose to use existing JavaScript SDK or community-contributed libraries in other languages (Python, PHP, Ruby) to simplify interaction with the API. These SDKs often abstract away HTTP requests and JSON parsing, allowing developers to focus on application logic.
• Commercial Use and Licensing: If your project scales beyond personal or non-commercial use, contact Hebcal directly to discuss commercial licensing. This ensures compliance with their terms of service and provides access to higher usage limits or specialized support. Details on this are available via the Hebrew Calendar homepage.

Troubleshooting the first call

Encountering issues during your first API call is a common part of the development process. Here are some troubleshooting steps and common problems to address:

• Incorrect URL or Parameters: Double-check the entire URL for typos, missing slashes, or incorrect parameter names. Ensure that all query parameters (like gy, gm, gd, cfg) are correctly spelled and have valid values. Refer to the Hebrew Calendar API documentation for the exact endpoint structure.
• Network Connectivity: Verify that your environment has internet access and can reach www.hebcal.com. Firewalls, proxies, or local network issues can prevent successful HTTP requests. You can test this by trying to access the API URL directly in a web browser.
• HTTP Status Codes: Pay attention to the HTTP status code returned in the response. Common codes and their meanings include:
  • 200 OK: Success. The request was processed correctly.
  • 400 Bad Request: The API server could not understand the request due to invalid syntax or parameters. This often points to issues with your URL construction or parameter values.
  • 404 Not Found: The requested resource (endpoint) does not exist. Check for typos in the base URL or endpoint path.
  • 5xx Server Error: An issue occurred on the API server's side. While less common for the Hebcal API, these indicate a problem beyond your control and might require waiting or contacting support if persistent. Consistent server errors could indicate a broader outage, as discussed in Cloudflare's HTTP status code guide.
• JSON Parsing Errors: If you receive a successful HTTP status (e.g., 200 OK) but your application fails to parse the response, inspect the raw response body. It might not be valid JSON, or it could be an unexpected format (e.g., HTML error page). Ensure you've set cfg=json in your request if you expect JSON. Some API responses might specify the MIME type in the Content-Type header, which can help confirm the format.
• Rate Limiting: While the free tier for personal and non-commercial use is generally generous, excessive requests in a short period might trigger temporary rate limiting. If your requests suddenly start failing with 429 Too Many Requests, pause your application and try again after a short interval. For commercial applications, consider implementing a backoff strategy.
• CORS Issues (Browser-based applications): If you are making requests from a web browser (e.g., using Fetch API or XMLHttpRequest in JavaScript), you might encounter Cross-Origin Resource Sharing (CORS) errors. These occur when a web page tries to make a request to a different domain than the one it originated from. The Hebrew Calendar API generally supports CORS for common requests, but if you face issues, ensure your browser is not blocking the request due to security settings or misconfiguration. The MDN Web Docs on CORS provide in-depth information.

By systematically checking these areas, you can often identify and resolve issues preventing your first successful interaction with the Hebrew Calendar API.