Skip to main content

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

Including hebcal.com content on other sites, advanced linking

Leyning (Torah Reading) API

Posted on by

We are pleased to offer support for REST API for Torah Reading for full kriyah leyning on Shabbat and holidays, Triennial (optionally) for Shabbat, and weekday readings on Mondays & Thursdays.

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

Here’s the basic URL format:

https://www.hebcal.com/leyning?cfg=json&start=2022-09-21&end=2022-09-26

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
  • For a single date:
    • date=2011-06-02 – Gregorian date in YYYY-MM-DD format
  • Or, for a date range:
    • start=2021-01-15 – start date using YYYY-MM-DD format
    • end=2021-01-22 – end date 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
  • Diaspora vs. Israel
    • i=off – Diaspora holidays and Torah readings (default if unspecified)
    • i=on – Israel holidays and Torah readings
  • triennial=off – reduce size of JSON response payload by disabling Triennial aliyot details (default on)

Example output

{
  "date": "2022-10-03T18:41:57.168Z",
  "location": "Diaspora",
  "range": {
    "start": "2022-09-21",
    "end": "2022-09-26"
  },
  "items": [
    {
      "date": "2022-09-22",
      "hdate": "26 Elul 5782",
      "name": {
        "en": "Nitzavim",
        "he": "נִצָּבִים"
      },
      "parshaNum": 51,
      "weekday": {
        "1": {"k": "Deuteronomy", "b": "29:9", "e": "29:11", "v": 3},
        "2": {"k": "Deuteronomy", "b": "29:12", "e": "29:14", "v": 3},
        "3": {"k": "Deuteronomy", "b": "29:15", "e": "29:28", "v": 14}
      }
    },
    {
      "date": "2022-09-24",
      "hdate": "28 Elul 5782",
      "name": {
        "en": "Nitzavim",
        "he": "נִצָּבִים"
      },
      "parshaNum": 51,
      "summary": "Deuteronomy 29:9-30:20",
      "fullkriyah": {
        "1": {"k": "Deuteronomy", "b": "29:9", "e": "29:11", "v": 3},
        "2": {"k": "Deuteronomy", "b": "29:12", "e": "29:14", "v": 3},
        "3": {"k": "Deuteronomy", "b": "29:15", "e": "29:28", "v": 14},
        "4": {"k": "Deuteronomy", "b": "30:1", "e": "30:6", "v": 6},
        "5": {"k": "Deuteronomy", "b": "30:7", "e": "30:10", "v": 4},
        "6": {"k": "Deuteronomy", "b": "30:11", "e": "30:14", "v": 4},
        "7": {"k": "Deuteronomy", "b": "30:15", "e": "30:20", "v": 6},
        "M": {"k": "Deuteronomy", "b": "30:15", "e": "30:20", "v": 6}
      },
      "haft": {"k": "Isaiah", "b": "61:10", "e": "63:9", "v": 23},
      "haftara": "Isaiah 61:10-63:9",
      "triennial": {
        "1": {"k": "Deuteronomy", "b": "29:9", "e": "29:11", "v": 3},
        "2": {"k": "Deuteronomy", "b": "29:12", "e": "29:14", "v": 3},
        "3": {"k": "Deuteronomy", "b": "29:15", "e": "29:28", "v": 14},
        "4": {"k": "Deuteronomy", "b": "30:1", "e": "30:6", "v": 6},
        "5": {"k": "Deuteronomy", "b": "30:7", "e": "30:10", "v": 4},
        "6": {"k": "Deuteronomy", "b": "30:11", "e": "30:14", "v": 4},
        "7": {"k": "Deuteronomy", "b": "30:15", "e": "30:20", "v": 6},
        "M": {"k": "Deuteronomy", "b": "30:15", "e": "30:20", "v": 6}
      },
      "triYear": 3,
      "triHaftara": "Isaiah 65:16-25",
      "triHaft": {"k": "Isaiah", "b": "65:16", "e": "65:25", "note": "terem yikrau ani e'eneh", "v": 10}
    },
    {
      "date": "2022-09-26",
      "hdate": "1 Tishrei 5783",
      "name": {
        "en": "Rosh Hashana I",
        "he": "רֹאשׁ הַשָּׁנָה א׳"
      },
      "fullkriyah": {
        "1": {"p": 4, "k": "Genesis", "b": "21:1", "e": "21:4", "v": 4},
        "2": {"p": 4, "k": "Genesis", "b": "21:5", "e": "21:12", "v": 8},
        "3": {"p": 4, "k": "Genesis", "b": "21:13", "e": "21:21", "v": 9},
        "4": {"p": 4, "k": "Genesis", "b": "21:22", "e": "21:27", "v": 6},
        "5": {"p": 4, "k": "Genesis", "b": "21:28", "e": "21:34", "v": 7},
        "M": {"p": 41, "k": "Numbers", "b": "29:1", "e": "29:6", "v": 6}
      },
      "summary": "Genesis 21:1-34; Numbers 29:1-6",
      "summaryParts": [
        {"k": "Genesis", "b": "21:1", "e": "21:34"},
        {"k": "Numbers", "b": "29:1", "e": "29:6"}
      ],
      "haft": {"k": "I Samuel", "b": "1:1", "e": "2:10", "v": 38},
      "haftara": "I Samuel 1:1-2:10"
    }
  ]
}

Yahrzeit + Anniversary REST API

Posted on by

We are pleased to offer support for REST API for personal Yahrzeits, Hebrew Birthdays and Hebrew Anniversaries.

Note that this is a web API with the same functionality as the getYahrzeit and getBirthdayOrAnniversary APIs 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.

Clients should POST x-www-form-urlencoded data to https://www.hebcal.com/yahrzeit

Regarding application/x-www-form-urlencoded: the keys and values are encoded in key-value tuples separated by '&', with a '=' between the key and the value. Non-alphanumeric characters in both keys and values are percent encoded.

The following parameters must be specified

  • cfg=json
  • v=yahrzeit

The following parameters may be specified once

  • years=3 – default 20. Use years=1 for only a single Hebrew year
  • hebdate=on – append Hebrew date to the event titles (default off)
  • yizkor=on – Include Yizkor dates (default off)
    • i=off – Diaspora Yizkor schedule (Pesach 8th day, Shavuot 2nd day, Yom Kippur and Shmini Atzeret)
    • i=on – Israel Yizkor schedule (Pesach 7th day, Shavuot, Yom Kippur and Shmini Atzeret)
  • start=5749 – beginning Hebrew year to calculate anniversary dates (defaults the current Hebrew year)
  • end=5761 – ending Hebrew year (inclusive) to calculate anniversary dates (defaults to start year + years years)
  • hdp=1 – include heDateParts field on untimed (all-day) items in the response

Then, specify at least one input date based on the Gregorian date of death (or birth). The following parameters are required, substituting the X with increasing integers beginning with 1.

  • yX=1983 – Gregorian year, 4-digit date
  • mX=4 – Gregorian month (1=January, 12=December; leading zeros optional)
  • dX=15 – Gregorian day of month (1-31; leading zeros optional)
  • sX=on – Event occurred on Gregorian date after sunset (default off implies that event occurred before sunset)
  • tX=Yahrzeit – type (either Yahrzeit, Birthday or Anniversary – case-sensitive)
  • nX=Plonit+ben+Ploni – name (optional)

Please take care to specify the correct tX type parameter (either Yahrzeit, Birthday or Anniversary). The algorithm (according to Ashkenazic practice) differs between these options, especially in the months of Adar, Cheshvan, or Kislev. For more information, see “How does Hebcal determine anniversaries (birthdays, yahrzeits)?“

Unlike other Hebcal.com REST APIs, this API requires HTTPS (either HTTP/1.1 or HTTP/2) due to the personal/sensitive nature of the information being passed across the Internet.

  • 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.

Example

Here is an example of two events, a Hebrew Birthday for Person1 and a Yahrzeit for Person2:

curl \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --compressed \
  --data-raw 'cfg=json&v=yahrzeit&n1=Person1&t1=Birthday&d1=15&m1=4&y1=1983&s1=on&n2=Person2&t2=Yahrzeit&d2=13&m2=11&y2=2008&s2=off&hebdate=on&years=3' \
  https://www.hebcal.com/yahrzeit

The response will be application/json that looks like this:

{
  "title": "Hebrew Anniversaries: Person1, Person2",
  "date": "2022-05-30T19:04:58.561Z",
  "range": {
    "start": "2021-10-21",
    "end": "2024-05-11"
  },
  "items": [
    {
      "title": "Person2's 13th Yahrzeit (15th of Cheshvan)",
      "date": "2021-10-21",
      "hdate": "15 Cheshvan 5782",
      "memo": "Hebcal joins you in remembering Person2, whose 13th Yahrzeit occurs on Thursday, October 21, corresponding to the 15th of Cheshvan, 5782.\n\nPerson2's Yahrzeit begins at sundown on Wednesday, October 20 and continues until sundown on the day of observance. It is customary to light a memorial candle at sundown as the Yahrzeit begins.\n\nMay your loved one's soul be bound up in the bond of eternal life and may their memory serve as a continued source of inspiration and comfort to you.",
      "name": "Person2",
      "category": "yahrzeit",
      "anniversary": 13
    },
    {
      "title": "Person1's 39th Hebrew Birthday (3rd of Iyyar)",
      "date": "2022-05-04",
      "hdate": "3 Iyyar 5782",
      "memo": "Hebcal joins you in honoring Person1, whose 39th Hebrew Birthday occurs on Wednesday, May 4, corresponding to the 3rd of Iyyar, 5782.\n\nPerson1's Hebrew Birthday begins at sundown on Tuesday, May 3 and continues until sundown on the day of observance.",
      "name": "Person1",
      "category": "birthday",
      "anniversary": 39
    },
    {
      "title": "Person2's 14th Yahrzeit (15th of Cheshvan)",
      "date": "2022-11-09",
      "hdate": "15 Cheshvan 5783",
      "memo": "Hebcal joins you in remembering Person2, whose 14th Yahrzeit occurs on Wednesday, November 9, corresponding to the 15th of Cheshvan, 5783.\n\nPerson2's Yahrzeit begins at sundown on Tuesday, November 8 and continues until sundown on the day of observance. It is customary to light a memorial candle at sundown as the Yahrzeit begins.\n\nMay your loved one's soul be bound up in the bond of eternal life and may their memory serve as a continued source of inspiration and comfort to you.",
      "name": "Person2",
      "category": "yahrzeit",
      "anniversary": 14
    },
    {
      "title": "Person1's 40th Hebrew Birthday (3rd of Iyyar)",
      "date": "2023-04-24",
      "hdate": "3 Iyyar 5783",
      "memo": "Hebcal joins you in honoring Person1, whose 40th Hebrew Birthday occurs on Monday, April 24, corresponding to the 3rd of Iyyar, 5783.\n\nPerson1's Hebrew Birthday begins at sundown on Sunday, April 23 and continues until sundown on the day of observance.",
      "name": "Person1",
      "category": "birthday",
      "anniversary": 40
    },
    {
      "title": "Person2's 15th Yahrzeit (15th of Cheshvan)",
      "date": "2023-10-30",
      "hdate": "15 Cheshvan 5784",
      "memo": "Hebcal joins you in remembering Person2, whose 15th Yahrzeit occurs on Monday, October 30, corresponding to the 15th of Cheshvan, 5784.\n\nPerson2's Yahrzeit begins at sundown on Sunday, October 29 and continues until sundown on the day of observance. It is customary to light a memorial candle at sundown as the Yahrzeit begins.\n\nMay your loved one's soul be bound up in the bond of eternal life and may their memory serve as a continued source of inspiration and comfort to you.",
      "name": "Person2",
      "category": "yahrzeit",
      "anniversary": 15
    },
    {
      "title": "Person1's 41st Hebrew Birthday (3rd of Iyyar)",
      "date": "2024-05-11",
      "hdate": "3 Iyyar 5784",
      "memo": "Hebcal joins you in honoring Person1, whose 41st Hebrew Birthday occurs on Saturday, May 11, corresponding to the 3rd of Iyyar, 5784.\n\nPerson1's Hebrew Birthday begins at sundown on Friday, May 10 and continues until sundown on the day of observance.",
      "name": "Person1",
      "category": "birthday",
      "anniversary": 41
    }
  ]
}

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 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.

Shabbat times REST API

Posted on by

We offer a simple API for looking up this week’s Shabbat times and Torah Portion. This API generates results for a given location on a rolling weekly time window. Weekly calculations change every Sunday at midnight in the city’s local time zone.

This API uses a similar URL and response format as our full Jewish calendar REST API, but offers less control over the dates and times. If you find you want more fine-grained control over the date ranges, or what kinds of events are included and which are excluded, we recommend using the full Jewish calendar REST API instead.

URL Format

The basic URL format is as follows:

https://www.hebcal.com/shabbat?cfg=json&geonameid=3448439&M=on

API Parameters

Note the following customizable parameters and their meanings:

  • cfg=json – output format is JSON (cfg=json) or RSS (cfg=r)
  • b=18 – Candle-lighting time minutes before sunset (the default is 18). For Jerusalem, the default is b=40
  • M=on – Havdalah at nightfall – 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)
  • m=50 – Havdalah 50 minutes after sundown. This option is available for those whose minhag is to end Shabbat a fixed number of minutes after 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. Set to m=0 (zero) to disable Havdalah times
  • leyning=off – include Torah and Haftarah for regular Shabbat (default on)

You can optionally specify an exact date, for example 13 February 2021. If unspecified, defaults to today.

  • gy=2021&gm=2&gd=13

You may optionally add &hdp=1 to include heDateParts field on untimed (all-day) items in the response.

Location parameter

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.

Event title language

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

Results

The returned JSON results includes a list of items that have a category will typically include each of the following:

  • candles – Candle-lighting on Friday or erev chag
  • parashat – Parashat HaShavua, the weekly Torah portion
  • havdalah – Havdalah, the end of Shabbat

Depending on the week of the year, other items may appear in the results, including

  • holiday (with subcat major or minor or fast)
  • zmanim (often with subcat fast for “Fast begins” or “Fast ends”)

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.

Example output

JSON (cfg=json)

{
  "title": "Hebcal São Paulo February 2015",
  "date": "2022-05-30T17:42:57.551Z",
  "location": {
    "title": "São Paulo, Sao 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
  },
  "range": {
    "start": "2015-02-20",
    "end": "2015-02-21"
  },
  "items": [
    {
      "title": "Rosh Chodesh Adar",
      "date": "2015-02-20",
      "hdate": "1 Adar 5775",
      "category": "roshchodesh",
      "hebrew": "ראש חודש אדר",
      "leyning": {
        "1": "Numbers 28:1-28:3",
        "2": "Numbers 28:3-28:5",
        "3": "Numbers 28:6-28:10",
        "4": "Numbers 28:11-28:15",
        "torah": "Numbers 28:1-15"
      },
      "link": "https://hebcal.com/h/rosh-chodesh-adar-2015?us=js&um=api",
      "memo": "Start of month of Adar on the Hebrew calendar. Adar (אַדָר) is the 12th month of the Hebrew year, has 29 days, and corresponds to February or March on the Gregorian calendar.  רֹאשׁ חוֹדֶשׁ, transliterated Rosh Chodesh or Rosh Hodesh, is a minor holiday that occurs at the beginning of every month in the Hebrew calendar. It is marked by the birth of a new moon"
    },
    {
      "title": "Candle lighting: 7:25pm",
      "date": "2015-02-20T19:25:00-02:00",
      "category": "candles",
      "title_orig": "Candle lighting",
      "hebrew": "הדלקת נרות",
      "memo": "Parashat Terumah"
    },
    {
      "title": "Parashat Terumah",
      "date": "2015-02-21",
      "hdate": "2 Adar 5775",
      "category": "parashat",
      "hebrew": "פרשת תרומה",
      "leyning": {
        "1": "Exodus 25:1-25:16",
        "2": "Exodus 25:17-25:30",
        "3": "Exodus 25:31-26:14",
        "4": "Exodus 26:15-26:30",
        "5": "Exodus 26:31-26:37",
        "6": "Exodus 27:1-27:8",
        "7": "Exodus 27:9-27:19",
        "torah": "Exodus 25:1-27:19",
        "haftarah": "I Kings 5:26-6:13",
        "maftir": "Exodus 27:17-27:19",
        "triennial": {
          "1": "Exodus 26:1-26:3",
          "2": "Exodus 26:4-26:6",
          "3": "Exodus 26:7-26:11",
          "4": "Exodus 26:12-26:14",
          "5": "Exodus 26:15-26:21",
          "6": "Exodus 26:22-26:25",
          "7": "Exodus 26:26-26:30",
          "maftir": "Exodus 26:26-26:30"
        }
      },
      "link": "https://hebcal.com/s/terumah-20150221?us=js&um=api"
    },
    {
      "title": "Havdalah: 8:17pm",
      "date": "2015-02-21T20:17:00-02:00",
      "category": "havdalah",
      "title_orig": "Havdalah",
      "hebrew": "הבדלה"
    }
  ]
}

RSS (cfg=r)

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"
  xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
  xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>Shabbat Times for São Paulo, Sao Paulo, Brazil</title>
    <link>https://www.hebcal.com/shabbat?geonameid=3448439&amp;M=on&amp;lg=s&amp;utm_source=shabbat1c&amp;utm_medium=rss</link>
    <atom:link href="https://www.hebcal.com/shabbat?cfg=r&amp;geonameid=3448439&amp;M=on&amp;lg=s&amp;pubDate=0" rel="self" type="application/rss+xml" />
    <description>Weekly Shabbat candle lighting times for São Paulo, Sao Paulo, Brazil</description>
    <language>en</language>
    <copyright>Copyright (c) 2022 Michael J. Radwin. All rights reserved.</copyright>
    <lastBuildDate>Mon, 30 May 2022 17:47:38 GMT</lastBuildDate>
    <item>
      <title>Rosh Chodesh Adar</title>
      <link>https://hebcal.com/h/rosh-chodesh-adar-2015?us=shabbat1c&amp;um=rss</link>
      <guid isPermaLink="false">https://www.hebcal.com/holidays/rosh-chodesh-adar-2015#20150220-rosh-chodesh-adar</guid>
      <description>Start of month of Adar on the Hebrew calendar. Adar (אַדָר) is the 12th month of the Hebrew year, has 29 days, and corresponds to February or March on the Gregorian calendar.  רֹאשׁ חוֹדֶשׁ, transliterated Rosh Chodesh or Rosh Hodesh, is a minor holiday that occurs at the beginning of every month in the Hebrew calendar. It is marked by the birth of a new moon</description>
      <category>roshchodesh</category>
      <pubDate>Mon, 30 May 2022 17:47:38 GMT</pubDate>
    </item>
    <item>
      <title>Candle lighting: 7:25pm</title>
      <link>https://www.hebcal.com/shabbat?geonameid=3448439&amp;M=on&amp;lg=s&amp;dt=2015-02-20&amp;utm_source=shabbat1c&amp;utm_medium=rss#20150220-candle-lighting</link>
      <guid isPermaLink="false">https://www.hebcal.com/shabbat?geonameid=3448439&amp;M=on&amp;lg=s&amp;dt=2015-02-20#20150220-candle-lighting</guid>
      <description>Friday, February 20, 2015</description>
      <category>candles</category>
      <pubDate>Mon, 30 May 2022 17:47:38 GMT</pubDate>
      <geo:lat>-23.5475</geo:lat>
      <geo:long>-46.63611</geo:long>
    </item>
    <item>
      <title>Parashat Terumah</title>
      <link>https://hebcal.com/s/terumah-20150221?us=shabbat1c&amp;um=rss</link>
      <guid isPermaLink="false">https://www.hebcal.com/sedrot/terumah-20150221#20150221-parashat-terumah</guid>
      <description>Torah: Exodus 25:1-27:19
Haftarah: I Kings 5:26-6:13</description>
      <category>parashat</category>
      <pubDate>Mon, 30 May 2022 17:47:38 GMT</pubDate>
    </item>
    <item>
      <title>Havdalah: 8:17pm</title>
      <link>https://www.hebcal.com/shabbat?geonameid=3448439&amp;M=on&amp;lg=s&amp;dt=2015-02-21&amp;utm_source=shabbat1c&amp;utm_medium=rss#20150221-havdalah</link>
      <guid isPermaLink="false">https://www.hebcal.com/shabbat?geonameid=3448439&amp;M=on&amp;lg=s&amp;dt=2015-02-21#20150221-havdalah</guid>
      <description>Saturday, February 21, 2015</description>
      <category>havdalah</category>
      <pubDate>Mon, 30 May 2022 17:47:38 GMT</pubDate>
    </item>
  </channel>
</rss>