Skip to main content

Assur Melacha (work forbidden) API

Posted on by

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.