Category Archives: Developers, APIs, RSS Feeds, Source Code

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.

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
4. elev=[1-9000] (optional) – elevation in meters. This parameter will be ignored unless ue=on, see below for further details.

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

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?

The Hebcal website and APIs support 13 different languages for event titles. By default, Hebcal uses Sephardic transliterations. To transliterate event titles in a different language, specify lg=LANG parameter using one of the following values:

For example, depending on which language is selected, the event title “Sukkot” will be transliterated as one of the following:

• Soukkot
• Sucos
• Sucot
• Sukkos
• Sukkot
• Sukot
• Szukkot
• Суккот
• סוּכּוֹת
• סוכות

We are pleased to offer an experimental Zmanim (halachic times) iCalendar feed. Many calendar desktop, mobile or web apps support the iCalendar (.ICS file extension) format.

You can specify your location using a GeoNames.org numeric ID, a United States ZIP code, or a geographic position (location specified by latitude, longitude, and timezone). You’ll find details on how to specify the location parameters on the Zmanim (halachic times) API page.

By default, event titles use a Sephardic transliteration. Append &lg=LANG to the URL to render the events titles using an alternate event language.

Option 1: All zmanim in a single daily untimed event

The basic URL format of the feeds is this:

webcal://download.hebcal.com/zmanim2?geonameid=5368361

The calendar feed will contain zmanim for the next 90 days. There will be a single all-day (untimed) event with the Hebrew date, and the description/notes will contain all times. Here is an example event:

Option 2: Timed events

If you would prefer approximately 20 timed events per day, we offer an alternate feed format using this alternate URL format (note /zmanim instead of /zmanim2 above):

webcal://download.hebcal.com/zmanim?zip=02906

The calendar feed will contain events for the next 60 days. Each event represents only a single halachic time.

Here’s an example of the events included in the calendar feed:

Option 3: Sunrise and Sunset only

An alternate feed which contains only sunrise and sunset events is available using URL format like this (note /sunrs instead of /zmanim2 above):

webcal://download.hebcal.com/sunrs?zip=02906

In this variation, there are only two events per day.

If you’d like to display today’s Omer count on your website and you’re comfortable with a bit of Javascript, you can use a snippet like this:

To display the Omer count in another language, change the &lg=s to another supported language code (for example h for Hebrew, es for Spanish, etc).

If you’d like to display the long omer count in English or Hebrew, you can dislay item.omer.count.en or item.omer.count.he

• he: “הַיוֹם שְׁמוֹנָה עָשָׂר יוֹם, שְׁהֵם שְׁנֵי שָׁבוּעוֹת וְאַרְבָּעָה יָמִים לָעוֹמֶר”,
• en: “Today is 18 days, which is 2 weeks and 4 days of the Omer”

See also item.omer.sefira.he, .en, and .translit.

• he: “נֶּֽצַח שֶׁבְּתִּפאֶרֶת”,
• translit: “Netzach sheb’Tiferet”,
• en: “Eternity within Beauty”