Skip to main content

Author Archives: mradwin

Zmanim (halachic times) API

Posted on by

Hebcal.com now offers a REST API for calculating zmanim (halachic times) for a given location.

Note that this is a web API with the same functionality as Zmanim 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&geonameid=3448439&date=2021-03-23

URL format for batch query (range of dates):

https://www.hebcal.com/zmanim?cfg=json&geonameid=3448439&start=2021-01-15&end=2021-01-22

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

Parameters and their meanings

  • cfg=json – output JSON. 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.

Date

Note the following optional date parameters and their meanings:

  • date=2021-03-23 – calculate zmanim for a single date using YYYY-MM-DD format
  • start=2021-01-15&end=2021-01-22 – calculate zmanim for a date range using YYYY-MM-DD format. Results will be truncated to 180 days if the end date is more than 180 days after the start date

If neither date format is specified, the API will return zmanim for today. Note that specifying the &date= parameter is preferred, because it’s more consistent, predictable, and improves cachability.

If your application needs to generate zmanim for multiple dates, it’s much more efficient to use the batch format (&start=YYYY-MM-DD&end=YYYY-MM-DD) than to make multiple API calls.

Precision

Update September 2022: an optional &sec=1 parameter may be specified to get seconds-level precision of times. The default if unspecified is to round times to the nearest minute.

Response format

The following Zmanim are included in the response:

chatzotNight – Midnight – Chatzot
Sunset plus 6 halachic hours
alotHaShachar – Dawn – Alot haShachar
Sun is 16.1° below the horizon in the morning
misheyakir – Earliest talis & tefillin – Misheyakir
Sun is 11.5° below the horizon in the morning
misheyakirMachmir – Earliest talis & tefillin – Misheyakir Machmir
Sun is 10.2° below the horizon in the morning
dawn – Civil dawn
Sun is 6° below the horizon in the morning
sunrise – Sunrise
Upper edge of the Sun appears over the eastern horizon in the morning (0.833° above horizon)
sofZmanShma – Latest Shema (Gra)
Sunrise plus 3 halachic hours, according to the Gra
sofZmanShmaMGA – Latest Shema (MGA)
Sunrise plus 3 halachic hours, according to Magen Avraham
sofZmanTfilla – Latest Shacharit (Gra)
Sunrise plus 4 halachic hours, according to the Gra
sofZmanTfillaMGA – Latest Shacharit (MGA)
Sunrise plus 4 halachic hours, according to Magen Avraham
chatzot – Midday – Chatzot
Sunrise plus 6 halachic hours
minchaGedola – Earliest Mincha – Mincha Gedola
Sunrise plus 6.5 halachic hours
minchaKetana – Preferable earliest time to recite Minchah – Mincha Ketana
Sunrise plus 9.5 halachic hours
plagHaMincha – Plag haMincha
Sunrise plus 10.75 halachic hours
sunset – Sunset
When the upper edge of the Sun disappears below the horizon (0.833° below horizon)
dusk – Civil dusk
Sun is 6° below the horizon in the evening
beinHaShmashos – Bein Hashemashot / Twilight
13.5 minutes prior to tzeit (nightfall) when the sun is 7.083° below horizon
tzeit7083deg – Nightfall (3 medium stars) – Tzeit 7.083°
When 3 medium stars are observable in the night sky with the naked eye (sun 7.083° below the horizon)
tzeit85deg – Nightfall (3 small stars) – Tzeit 8.5°
When 3 small stars are observable in the night sky with the naked eye (sun 8.5° below the horizon)
tzeit42min – Nightfall (3 medium stars) – Tzeit 42 minutes
When 3 medium stars are observable in the night sky with the naked eye (fixed 42 minutes after sunset)
tzeit50min – Nightfall (3 small stars) – Tzeit 50 minutes
When 3 small stars are observable in the night sky with the naked eye (fixed 50 minutes after sunset)
tzeit72min – Nightfall (Rabbeinu Tam) – Tzeit 72 minutes
When 3 small stars are observable in the night sky with the naked eye (fixed 72 minutes after sunset)

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.

Example output (single date)

{
  "date": "2021-03-23",
  "location": {
    "latitude": -23.5475,
    "longitude": -46.63611,
    "il": false,
    "tzid": "America/Sao_Paulo",
    "name": "São Paulo, Sao Paulo, Brazil",
    "cc": "BR",
    "geoid": 3448439,
    "geo": "geoname",
    "geonameid": 3448439,
    "asciiname": "Sao Paulo",
    "admin1": "Sao Paulo",
    "population": 10021295
  },
  "times": {
    "chatzotNight": "2021-03-23T00:13:00-03:00",
    "alotHaShachar": "2021-03-23T05:05:00-03:00",
    "misheyakir": "2021-03-23T05:25:00-03:00",
    "misheyakirMachmir": "2021-03-23T05:31:00-03:00",
    "dawn": "2021-03-23T05:49:00-03:00",
    "sunrise": "2021-03-23T06:11:00-03:00",
    "sofZmanShma": "2021-03-23T09:12:00-03:00",
    "sofZmanShmaMGA": "2021-03-23T08:36:00-03:00",
    "sofZmanTfilla": "2021-03-23T10:12:00-03:00",
    "sofZmanTfillaMGA": "2021-03-23T09:48:00-03:00",
    "chatzot": "2021-03-23T12:13:00-03:00",
    "minchaGedola": "2021-03-23T12:43:00-03:00",
    "minchaKetana": "2021-03-23T15:44:00-03:00",
    "plagHaMincha": "2021-03-23T16:59:00-03:00",
    "sunset": "2021-03-23T18:14:00-03:00",
    "dusk": "2021-03-23T18:37:00-03:00",
    "tzeit7083deg": "2021-03-23T18:41:00-03:00",
    "tzeit85deg": "2021-03-23T18:48:00-03:00",
    "tzeit42min": "2021-03-23T18:56:00-03:00",
    "tzeit50min": "2021-03-23T19:04:00-03:00",
    "tzeit72min": "2021-03-23T19:26:00-03:00"
  }
}

Sample output (batch)

{
  "date": {
    "start": "2021-01-15",
    "end": "2021-01-18"
  },
  "location": {
    "latitude": -23.5475,
    "longitude": -46.63611,
    "il": false,
    "tzid": "America/Sao_Paulo",
    "name": "São Paulo, Sao Paulo, Brazil",
    "cc": "BR",
    "geoid": 3448439,
    "geo": "geoname",
    "geonameid": 3448439,
    "asciiname": "Sao Paulo",
    "admin1": "Sao Paulo",
    "population": 10021295
  },
  "times": {
    "chatzotNight": {
      "2021-01-15": "2021-01-15T00:16:00-03:00",
      "2021-01-16": "2021-01-16T00:16:00-03:00",
      "2021-01-17": "2021-01-17T00:17:00-03:00",
      "2021-01-18": "2021-01-18T00:17:00-03:00"
    },
    "alotHaShachar": {
      "2021-01-15": "2021-01-15T04:18:00-03:00",
      "2021-01-16": "2021-01-16T04:19:00-03:00",
      "2021-01-17": "2021-01-17T04:20:00-03:00",
      "2021-01-18": "2021-01-18T04:21:00-03:00"
    },
    "misheyakir": {
      "2021-01-15": "2021-01-15T04:41:00-03:00",
      "2021-01-16": "2021-01-16T04:42:00-03:00",
      "2021-01-17": "2021-01-17T04:43:00-03:00",
      "2021-01-18": "2021-01-18T04:44:00-03:00"
    },
    "misheyakirMachmir": {
      "2021-01-15": "2021-01-15T04:48:00-03:00",
      "2021-01-16": "2021-01-16T04:49:00-03:00",
      "2021-01-17": "2021-01-17T04:50:00-03:00",
      "2021-01-18": "2021-01-18T04:50:00-03:00"
    },
    "dawn": {
      "2021-01-15": "2021-01-15T05:09:00-03:00",
      "2021-01-16": "2021-01-16T05:09:00-03:00",
      "2021-01-17": "2021-01-17T05:10:00-03:00",
      "2021-01-18": "2021-01-18T05:11:00-03:00"
    },
    "sunrise": {
      "2021-01-15": "2021-01-15T05:33:00-03:00",
      "2021-01-16": "2021-01-16T05:34:00-03:00",
      "2021-01-17": "2021-01-17T05:35:00-03:00",
      "2021-01-18": "2021-01-18T05:36:00-03:00"
    },
    "sofZmanShma": {
      "2021-01-15": "2021-01-15T08:55:00-03:00",
      "2021-01-16": "2021-01-16T08:55:00-03:00",
      "2021-01-17": "2021-01-17T08:56:00-03:00",
      "2021-01-18": "2021-01-18T08:56:00-03:00"
    },
    "sofZmanShmaMGA": {
      "2021-01-15": "2021-01-15T08:19:00-03:00",
      "2021-01-16": "2021-01-16T08:19:00-03:00",
      "2021-01-17": "2021-01-17T08:19:00-03:00",
      "2021-01-18": "2021-01-18T08:20:00-03:00"
    },
    "sofZmanTfilla": {
      "2021-01-15": "2021-01-15T10:02:00-03:00",
      "2021-01-16": "2021-01-16T10:02:00-03:00",
      "2021-01-17": "2021-01-17T10:03:00-03:00",
      "2021-01-18": "2021-01-18T10:03:00-03:00"
    },
    "sofZmanTfillaMGA": {
      "2021-01-15": "2021-01-15T09:38:00-03:00",
      "2021-01-16": "2021-01-16T09:38:00-03:00",
      "2021-01-17": "2021-01-17T09:38:00-03:00",
      "2021-01-18": "2021-01-18T09:39:00-03:00"
    },
    "chatzot": {
      "2021-01-15": "2021-01-15T12:16:00-03:00",
      "2021-01-16": "2021-01-16T12:16:00-03:00",
      "2021-01-17": "2021-01-17T12:17:00-03:00",
      "2021-01-18": "2021-01-18T12:17:00-03:00"
    },
    "minchaGedola": {
      "2021-01-15": "2021-01-15T12:50:00-03:00",
      "2021-01-16": "2021-01-16T12:50:00-03:00",
      "2021-01-17": "2021-01-17T12:50:00-03:00",
      "2021-01-18": "2021-01-18T12:50:00-03:00"
    },
    "minchaKetana": {
      "2021-01-15": "2021-01-15T16:11:00-03:00",
      "2021-01-16": "2021-01-16T16:11:00-03:00",
      "2021-01-17": "2021-01-17T16:11:00-03:00",
      "2021-01-18": "2021-01-18T16:11:00-03:00"
    },
    "plagHaMincha": {
      "2021-01-15": "2021-01-15T17:35:00-03:00",
      "2021-01-16": "2021-01-16T17:35:00-03:00",
      "2021-01-17": "2021-01-17T17:35:00-03:00",
      "2021-01-18": "2021-01-18T17:35:00-03:00"
    },
    "sunset": {
      "2021-01-15": "2021-01-15T18:59:00-03:00",
      "2021-01-16": "2021-01-16T18:58:00-03:00",
      "2021-01-17": "2021-01-17T18:58:00-03:00",
      "2021-01-18": "2021-01-18T18:58:00-03:00"
    },
    "dusk": {
      "2021-01-15": "2021-01-15T19:23:00-03:00",
      "2021-01-16": "2021-01-16T19:23:00-03:00",
      "2021-01-17": "2021-01-17T19:23:00-03:00",
      "2021-01-18": "2021-01-18T19:23:00-03:00"
    },
    "tzeit7083deg": {
      "2021-01-15": "2021-01-15T19:29:00-03:00",
      "2021-01-16": "2021-01-16T19:29:00-03:00",
      "2021-01-17": "2021-01-17T19:28:00-03:00",
      "2021-01-18": "2021-01-18T19:28:00-03:00"
    },
    "tzeit85deg": {
      "2021-01-15": "2021-01-15T19:36:00-03:00",
      "2021-01-16": "2021-01-16T19:35:00-03:00",
      "2021-01-17": "2021-01-17T19:35:00-03:00",
      "2021-01-18": "2021-01-18T19:35:00-03:00"
    },
    "tzeit42min": {
      "2021-01-15": "2021-01-15T19:41:00-03:00",
      "2021-01-16": "2021-01-16T19:40:00-03:00",
      "2021-01-17": "2021-01-17T19:40:00-03:00",
      "2021-01-18": "2021-01-18T19:40:00-03:00"
    },
    "tzeit50min": {
      "2021-01-15": "2021-01-15T19:49:00-03:00",
      "2021-01-16": "2021-01-16T19:48:00-03:00",
      "2021-01-17": "2021-01-17T19:48:00-03:00",
      "2021-01-18": "2021-01-18T19:48:00-03:00"
    },
    "tzeit72min": {
      "2021-01-15": "2021-01-15T20:11:00-03:00",
      "2021-01-16": "2021-01-16T20:10:00-03:00",
      "2021-01-17": "2021-01-17T20:10:00-03:00",
      "2021-01-18": "2021-01-18T20:10:00-03:00"
    }
  }
}

Hebcal 2020 year-end updates

Posted on by

At the conclusion of Gregorian year 2020, we’d like to express our thanks and gratitude to all of our Hebcal.com users. Our mission is to increase awareness of Jewish holidays and to help Jews to be observant of the mitzvot, and many of you have been visiting our site for calendar updates and Hebrew date conversion for years.

Here is a summary of updates we’ve made to Hebcal.com during the past 6 months.

Yahrzeit, Birthday and Anniversary calendar

We now offer annual email reminders for our Yahrzeit, Birthday and Anniversary calendar. After entering and confirming your email address, you will receive a reminder email 7 days before each anniversary. Our email privacy policy is the same as for our Shabbat weekly email list: We will never sell or give your email address to anyone. We will never use your email address to send you unsolicited offers.

In addition, Yahrzeit and anniversary calendar downloads for Apple, Google & Outlook now support more than 3 names. Just click the “+ Add another name” button to create another row and enter the additional details.

Zmanim (halachic times)

In August 2020 we updated our solar calculation engine, which has enabled several new features:

Havdalah can now be calculated according to tzeit hakochavim, the point when 3 small stars are observable in the night time sky with the naked eye. The new default Havdalah option is calculated when the sun is 8.5° below the horizon. This option is an excellent default for most places on the planet. We still offer the option to use a fixed number of minutes past sundown (e.g. 42 min for three medium-sized stars, 50 min for three small stars, 72 min for Rabbeinu Tam) which works well for Israel, most of the USA and Europe.

Fast start and end times are now provided for major fast (Tish’a B’Av) and minor fasts (Ta’anit Esther, Tzom Gedaliah, Tzom Tammuz, Asara B’Tevet, & Ta’anit Bechorot). Minor fasts begin at alot hashachar (when the sun is 16.1° below the horizon in the morning) and end when 3 medium-sized stars are observable in the night sky (when the sun is 7.083° below the horizon in the evening). Tish’a B’Av fast begins at sundown and ends when 3 medium-sized stars are observable.

Chanukah candle-lighting has been updated to occur at dusk on weekdays (when the sun is 6° below the horizon in the evening). To avoid any conflict with Shabbat, candle-lighting times for Chanukah on Friday night are 18 minutes before sundown (same as regular Shabbat candle-lighting) and at regular Havdalah time on Saturday night.

Language support

Earlier in December, we added Spanish language support for event title translations and transliterations. Hebcal now supports the following languages:

  • Sephardic transliterations
  • Ashkenazis transliterations
  • Hebrew – עברית
  • Spanish – español
  • French – français
  • Russian – ру́сский язы́к
  • Polish – język polski
  • Finnish – Suomalainen
  • Hungarian – Magyar nyelv
  • Sephardic translit. + Hebrew
  • Ashkenazis translit. + Hebrew

These languages are fully supported on the Custom Calendar generator and its associated export formats (Apple, Google, iCalendar, CSV, Print PDF) and the printable Candle-lighting Times Year at a Glance (“refrigerator times”) page.

Torah Readings

Holiday Torah readings are now included in the description/memo section of Apple, Google, & Outlook calendar feeds and our downloadable Torah reading spreadsheets (aliyah-by-aliyah breakdown especially useful for synagogue or minyan leyning coordinators). Previously only regular Shabbat Torah readings were included.

Aliyot for special Shabbatot that include three Sifrei Torah have been improved. We read from three Sifrei Torah when Rosh Chodesh coincides with Shabbat HaCodesh, Shabbat Shekalim or Shabbat Chanukah. Although some minyanim have the custom of reading 8 aliyot, we now take the more common approach of including the typical 7 aliyot for Shabbat. The 1st Sefer Torah is for regular Torah reading (aliyot 1-6), the 2nd Sefer Torah is read for the 7th aliyah for Rosh Chodesh (Numbers 28:9-15) and the 3rd Sefer Torah is read for the maftir aliyah (the special Shabbat).

Triennial Torah reading is now supported for Hebrew years 5745 through 5830 (Gregorian years 1984 – 2070).

Parsha detail pages now take into consideration the differences between the Israel and Diaspora sedra schemes. For example, in the year 5782 Parashat Achrei Mot is read on April 30, 2022 in the Diaspora and on April 23, 2022 in Israel.

Miscellaneous

Hebrew Date Converter now lists holidays and Parsha HaShavuah for any date from the year 0001-9999. Previously it converted dates but only mentioned holidays & parsha for years 1900-2099.

When the 9th of Av falls on Shabbat and the Tish’a B’Av fast is postponed to the 10th, the calendar event now says “Tish’a B’Av (observed)”.

The Hebrew typeface used on the website is now SBL Hebrew Font (copyright Society of Biblical Literature and Tiro Typeworks). This typeface is a more traditional serif style, which improves legibility.

We have discontinued support for Palm DateBook Archive calendar downloads.

How accurate are candle lighting times?

Posted on by

Candle-lighting and Havdalah times are derived from sunset times, which are approximated from a location (latitude, longitude) and day of year. As of August 2020, Hebcal.com calculates zmanim (halachic times) using an algorithm published by the US National Oceanic and Atmospheric Administration. The NOAA solar calculator is based on equations from Astronomical Algorithms by Jean Meeus.

The sunrise and sunset results are theoretically accurate to within a minute for locations between +/- 72° latitude, and within 10 minutes outside of those latitudes. However, due to variations in atmospheric composition, temperature, pressure and conditions, observed values may vary from calculations.

Solar Calculation Details, NOAA

Differences of 1-2 minutes between Hebcal and other sources publishing candle lighting times or sunset times are expected. Remember that candle lighting times can only be approximated based on location.

Here are a few common reasons why you may see differences in candle lighting times:

1. Different minhag on when to light candles

Hebcal defaults to 18 minutes before sundown for most locations (notable exceptions include 40 minutes before sundown for Jerusalem, 30 minutes for Haifa). Other sources may use 20 minutes before sundown. Hebcal gives an option to specify a different number of minutes before sunset if you don’t follow the 18-minute minhag.

2. Different sunrise/sunset calculation engines

The sunset calculator we use on Hebcal.com as of August 2020 uses an algorithm published by the US National Oceanic and Atmospheric Administration. Hebcal’s NOAA algorithm is implemented in JavaScript using double-precision floating point arithmetic. Other sources may use a slightly different algorithm, for example from the United States Naval Observatory (USNO).

Even if the other source also uses the NOAA algorithm, the implementation could differ slightly; there are many constants and opportunities to round and truncate which could result in slight differences in the final calculated sunset time for a given day and location. For example, in December 2023, Hebcal switched to a different NOAA implementation that optionally supports elevation (more on this below). Even when the elevation feature is disabled, this alternate calculation engine resulted in small differences (often less than 10 seconds) versus Hebcal’s previous NOAA engine.

3. Different latitude/longitude definitions for a given city

Since 2013, Hebcal.com has been using lat/long definitions from GeoNames.org, which is available under a Creative Commons license. For the USA, we purchase a commercial ZIP code database from zip-codes.com that provides latitude and longitude for the “center” of each zipcode. For very large cities, the sunset at the east side of the city might be a minute earlier than the west side of the city.

4. Deliberate rounding down (or up)

Hebcal rounds candle lighting (Friday) times down to the nearest minute, and rounds Havdalah times up to the nearest minute. To be more precise, we use the floor minute for candle-lighting, and we use the standard mathematical rounding rule for Havdalah. The idea here is that it’s better to display candle-lighting time as much as 59 seconds earlier than strictly necessary, and for Havdalah it’s better to wait an additional 30 seconds to end Shabbat/yontiff.

For example, if the exact candle lighting time from the sunset engine (including seconds) was at 20:02:31 or even 20:02:59, Hebcal displays candle-lighting as 20:02.

On the other hand, if the Havdalah calculation is 21:17:29, Hebcal will display 21:17. If it were 21:17:30 through 21:17:59, Hebcal displays 21:18.

5. Havdalah minutes past sundown versus sun degrees below horizion

As of August 2020, options for Havdalah times have also changed. Hebcal now offers an option to use tzeit hakochavim, the point when 3 small stars are observable in the night sky with the naked eye (sun 8.5° below the horizon). This option is an excellent default for most places on the planet. We also offer the option to use a fixed number of minutes past sundown. Typically one would enter 42 min for three medium-sized stars, 50 min for three small stars, 72 min for Rabbeinu Tam, or 0 to suppress Havdalah times.

6. Elevation above sea level

As of December 2023, the Hebcal sunrise/sunset algorithm has been enhanced to optionally include the elevation of the location. If selected, Hebcal will include the city’s elevation in the calculation of all sunrise/sunset based zmanim. Elevation will affect the result only for calculations that are a fixed number of minutes before or after sunrise/sunset.

For cities at a high elevation (for example Denver Colorado or Mexico City), including elevation above sea level can change the estimated sunset time by as much as 7 minutes. If you want to learn more, our friends at KosherJava have a short article entitled How Much Earlier is Sunrise on Mount Everest Due to Elevation?

Degree-based zmanim (for example the “nightfall” option for Havdalah, or the start time of minor fasts at Alot haShachar) are driven by the amount of light in the sky and are therefore not impacted by elevation.

To enable the elevation option, select the “Include elevation in sunrise/sunset estimate” radio button as displayed in the screenshot below:

Conclusion

Lastly, remember that the NOAA algorithm can only approximate the candle-lighting times for your location. If you ever have any doubts about Hebcal’s times, consult your local halachic authority.

Hebcal Developer API minor updates

Posted on by

We’re pleased to share a couple of brief and minor updates to our collection of Developer APIs.

  1. We now recommend using HTTPS for all of our APIs. We’ve updated our documentation to reflect this. Most of our JSON APIs still support HTTP. Some of our APIs now return a 301 redirect from the HTTP version to the HTTPS version.

  2. We implemented some simplistic rate-limiting to throttle clients who are sending too many API queries. You may receive a 429 “Too Many Requests” error if your client makes more than 90 requests in a 10-second window. Remember, this is a free service; please be polite and send batch API requests slowly over a longer period of time.