Skip to main content

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

Location must be specified by one of the following mutually exclusive parameters:

  • GeoNames.org numeric ID
    • requires additional parameter geonameid=3448439
    • Hebcal.com supports over 100,000 different GeoNames IDs. These are world cities with a population of 1,000 or more. See cities1000.zip from https://download.geonames.org/export/dump/.
  • United States ZIP code
    • requires additional parameter zip=90210
  • Geographic position: location specified by latitude, longitude, and timezone. Requires additional 3 parameters:
    • latitude=[-90.0 to 90.0] – latitude in decimal format (e.g. 31.76904 or -23.5475)
    • longitude=[-180.0 to 180.0] – longitude decimal format (e.g. 35.21633 or -46.63611)
    • 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
  • One of ~400 legacy Hebcal city identifiers
    • requires additional parameter city=GB-London
    • deprecated: geo=geoname is preferred

Elevation for sunset calculation

  • ue=on – use elevation for location (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

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)

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"
    }
  }
}