Skip to main content

Assur Melacha (work forbidden) API

Hebcal.com now offers an experimental REST API for determining for a given location if the date and time has a melacha (work) prohibition. This API can be used by home automation systems or other applications that wish to change functionality when Shabbat or yontiff begins or ends.

Although there are many opinions on the time of tzais, for simplicity this function uses solar depression of 8.5 degrees. More about Havdalah.

Note that this is a web API with the same functionality as the isAssurBemlacha API provided by the JavaScript @hebcal/core package. If you’re building a JavaScript application, consider using the native JS library instead of web APIs for a faster user experience.

The basic URL format is as follows:

https://www.hebcal.com/zmanim?cfg=json&im=1&geonameid=3448439&dt=2025-06-21T20:08:10Z

Parameters and their meanings

  • cfg=json – output JSON. Required
  • im=1 – enable issur melacha mode. Required
  • Location: Specify the desired location using GeoNames.org numeric ID, United States ZIP code, or latitude/longitude. This page also describes how to enable/disable the optional elevation for sunset calculation.
  • dt=YYYY-MM-DDTHH:mm:ss.sssZ – optionally specify an exact time to check
    • If specified, the date-time must follow the ISO 8601 Date time string format
      • Note Z is the timezone offset, which can either be the literal character Z (indicating UTC), or + or - followed by HH:mm, the offset in hours and minutes from UTC. If using a UTC positive time zone offset, take care to url-encode the + as %2b
      • If the date-time does not end with a time zone offset, the time will be interpreted as the local timezone of the location specified
    • If this optional date-time parameter is absent, the API will use the current local time at the location

Example output

{
  "date": "2025-06-23T04:52:52.475Z",
  "version": "5.10.0-3.4.1",
  "location": {
    "title": "São Paulo, Brazil",
    "city": "São Paulo",
    "tzid": "America/Sao_Paulo",
    "latitude": -23.5475,
    "longitude": -46.63611,
    "cc": "BR",
    "country": "Brazil",
    "admin1": "Sao Paulo",
    "asciiname": "Sao Paulo",
    "geo": "geoname",
    "geonameid": 3448439
  },
  "status": {
    "localTime": "2025-06-21T17:08:10-03:00",
    "isAssurBemlacha": true
  }
}

Usage notes

As with all Hebcal.com REST APIs:

  • Both HTTP and HTTPS (HTTP/2) are supported. Although most of the Web has moved to HTTPS, if you wish to reduce CPU overhead on your client you may continue to use plain (port 80) HTTP for API requests
  • We encourage HTTP caching proxies. Proper Cache-Control and Expires are generated in the response
  • We support both gzip and br (brotli) compression; set the appropriate Accept-Encoding header in your request to enable
  • We support HTTP Keep-Alive for multiple requests

Licensing

Content generated by the Hebcal.com web APIs is licensed under a Creative Commons Attribution 4.0 International License. This means that you can use you are free to copy and redistribute the material in any medium or format as long as you give appropriate credit to Hebcal.com.

Four New Years on the Hebrew calendar

There are four “New Years” mentioned in the Mishnah (Tractate Rosh Hashanah 1:1), each signifying a new beginning for different aspects of life: 1 Tishrei (Rosh Hashanah), 1 Nisan (for kings and festivals), 1 Elul (for tithes), and Tu Bishvat (for trees).

Here’s a breakdown:

1st of Tishrei – Rosh Hashana – New Year for Years

This is the most widely known Jewish New Year, marking the beginning of the Jewish calendar year and the start of the High Holy Days. On Rosh Hashanah, the calendar year changes (for example, from 5785 to 5786). It’s the beginning of the agricultural, financial, and legal year (like Sabbatical years and Jubilee years).

The Torah never refers to the first day of the seventh month as Rosh ha-Shanah. That term first appears in Ezek. 40:1. In the Torah, it is called a “day of remembrance” or “a day of sounding the shofar.” Readers may be surprised to learn that Rosh ha-Shanah begins the seventh month of the Hebrew calendar rather than the first. It commemorates the creation of the world, which traditionally is believed to have happened in the fall, the beginning of the new agricultural cycle. But the people Israel date their calendar from the Exodus, which happened in the spring (cf. Exod. 12:2 designating the month of the Exodus as the first month of Israel’s calendar).

[Etz Hayim: Torah and Commentary, pp. 727-728]

תִּשְׁרֵי (transliterated Tishrei or Tishri) is described in the Torah as the 7th month of the Hebrew year.

Timing: Early fall (September–October on the Gregorian calendar)

15th of Sh’vat – Tu BiShvat – New Year for Trees

This marks the beginning of the agricultural cycle for trees in Israel. It’s when the tithes from fruit trees were calculated. Today, it’s celebrated as an environmental and agricultural holiday, often called the “Jewish Arbor Day.”

שְׁבָט (transliterated Sh’vat or Shevat) is described in the Torah as the 11th month of the Hebrew year.

Timing: Winter (January–February on the Gregorian calendar)

1st of Nisan – New Year for Kings and Festivals

This is when the reigns of Jewish kings were counted (regardless of when they actually began ruling — it was “bumped up” to Nisan). It’s also significant for the religious calendar, as Nisan is the month of Passover and marks the Exodus from Egypt. In the Torah, Nisan is considered the first month of the year.

Timing: Spring (March–April on the Gregorian calendar)

נִיסָן (transliterated Nisan or Nissan) is described in the Torah as the 1st month of the Hebrew year.

1st of Elul – New Year for Tithing Animals

This was the cut-off date for determining which animals had to be tithed in Temple times. Animals born before and after Elul 1 were counted separately for the tithe.

Elul (אֱלוּל) is described in the Torah as the 6th month of the Hebrew year.

Timing: Late summer (August-early September on the Gregorian calendar)

Conclusion

You may notice that the Bible speaks of Rosh Hashanah as occurring on the first day of the seventh month. The first month of the Jewish calendar is Nissan, occurring in March and April. Why, then, does the Jewish “new year” occur in Tishri, the seventh month?

Judaism has several different “new years,” a concept which may seem strange at first, but think of it this way: the American “new year” starts in January, but the new “school year” starts in September, and many businesses have “fiscal years” that start at various times of the year.

[via Rosh Hashanah – Judaism 101 (JewFAQ)]

Specifying a location for Jewish calendar APIs

Hebcal.com Web APIs allow the developer to specify a location using one of four options.

Location is used to estimate candle-lighting, Havdalah, fast start/end times, and other zmanim (halachic times). All of these times are derived from a solar position calculation, which are approximated from a location (latitude, longitude) and day of year.

Option 1: GeoNames

To specify a location using a GeoNames numeric ID, use the geonameid parameter, e.g. geonameid=3448439

The GeoNames geographical database covers all countries and contains over eleven million placenames that are available for download free of charge. Hebcal.com supports a subset of the full database: approximately 150,000 world cities with a population of 1,000 or more.

For a complete list of IDs that the Hebcal.com web APIs accept, download the cities1000.zip from https://download.geonames.org/export/dump/ and consider only rows with a type of P (inhabited place). Hebcal refreshes this database approximately once per year.

Option 2: United States ZIP code

To specify a location using a 5-digit ZIP code in the US, use the zip parameter, e.g. zip=90210

If a longer ZIP code (for example a ZIP+4) is specified, only the first 5 digits will be considered.

Hebcal licenses a commercial ZIP code database and we refresh this database approximately once per year.

Option 3: Latitude and Longitude

To specify a location using a latitude and longitude and timezone, use 3 required parameters and one optional parameter.

  1. latitude=[-90.0 to 90.0] – latitude in decimal format (e.g. 31.76904 or -23.5475)
  2. longitude=[-180.0 to 180.0] – longitude decimal format (e.g. 35.21633 or -46.63611)
  3. tzid=TimezoneIdentifier. See List of tz database time zones

Be sure to use the “TZ database name” such as America/New_York or Europe/Paris, not a UTC offset.

An optional parameter elev=[1-9000] may also be used to specify the elevation in meters. This parameter will be ignored unless ue=on, see below for further details.

Option 4: Legacy city identifier (deprecated)

To specify a location using one of ~400 Hebcal legacy city identifiers, use the city parameter, e.g. city=GB-London

You must use one of the legacy city identifiers. Case insensitive. This approach is generally deprecated, as we now recommend using geonameid instead.

Elevation

All of the above options can optionally utilize an elevation for sunset calculation. To enable elevation, specify ue=on (default off).

If on, use elevation to affect the calculation of all sunrise/sunset based zmanim. Note: there are some zmanim such as degree-based zmanim that are driven by the amount of light in the sky and are not impacted by elevation. These zmanim intentionally do not support elevation adjustment

Accuracy

For more information on the calculation engine, see How accurate are candle lighting times?

Yahrzeit calendar search

Hebcal’s Yahrzeit + Anniversary calendar lets you create a personal list of Yahrzeit (memorial) and Yizkor dates, Hebrew Birthdays and Anniversaries for 20+ years. Once your personal list has been created, you can subscribe to free annual email reminders & calendar downloads to Apple, Google, Outlook, and more.

To keep things simple, Hebcal does not require any user registration or login. After creating your calendar, you may optionally sign up to receive annual reminder emails (sent one week before and one day before each anniversary).

If you have signed up for annual email reminders and would like to view or make changes to an existing calendar, the easiest way to find your calendar is by searching for an existing Yahrzeit + Anniversary Calendar by email address. If your email address is found, a confirmation email message will be sent to your email address containing personal calendar link(s). Click the link(s) within that message to view your personal calendars.

Yizkor Memorial Prayer

Yizkor (Hebrew: יִזְכּוֹר) is an Ashkenazi Jewish memorial prayer service for the dead. Yizkor is recited in synagogue as part of the service during four holidays each year:

  1. Yom Kippur
  2. Shmini Atzeret
  3. The final day of Passover (8th day Pesach in Diaspora, 7th day Pesach in Israel)
  4. Shavuot (2nd day Shavuot in Diaspora)

Select the “Include Yizkor dates” option when you create your personal Hebcal Yahrzeit + Anniversary calendar to be reminded of these dates.

Read more about Yikzor from My Jewish Learning, Chabad, and Wikipedia.

Yahrzeit refers to the anniversary, according to the Hebrew calendar, of the day of death of a loved one.