Author Archives: mradwin

We offer a simple API for converting between Gregorian and Hebrew dates. Two output formats are supported: JSON and XML.

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

1. Gregorian to Hebrew – single

To convert from Gregorian to Hebrew date use this URL format:

https://www.hebcal.com/converter?cfg=json&date=2011-06-02&g2h=1&strict=1

• cfg=json – output format is JSON (cfg=json) or XML (cfg=xml)
• g2h=1 – Convert from Gregorian to Hebrew date
• date=2011-06-02 – Gregorian date in YYYY-MM-DD format
• gs=on – After sunset on Gregorian date
• strict=1 – strict mode will return a 400 Bad Request error for invalid dates

As an alternative to specifying date=YYYY-MM-DD, clients may send gy=YYYY&gm=MM&gd=DD as follows:

• gy=2011 – Gregorian year
• gm=6 – Gregorian month (1=January, 12=December). Leading 0 is optional
• gd=2 – Gregorian day of month. Leading 0 is optional

2. Gregorian to Hebrew – range of dates

To convert a batch of Gregorian dates to Hebrew dates, use this URL format:

https://www.hebcal.com/converter?cfg=json&start=2021-12-29&end=2022-01-04&g2h=1

• cfg=json – output format is JSON (cfg=json)
• g2h=1 – Convert from Gregorian to Hebrew date
• start=2021-12-29 – Gregorian start date in YYYY-MM-DD format
• end=2022-01-04 – Gregorian end date in YYYY-MM-DD format

Results will be truncated to 180 days if the end date is more than 180 days after the start date.

3. Hebrew to Gregorian – single date

To convert from Hebrew to Gregorian use this URL format:

https://www.hebcal.com/converter?cfg=json&hy=5749&hm=Kislev&hd=25&h2g=1&strict=1

• cfg=json – output format is JSON (cfg=json) or XML (cfg=xml)
• h2g=1 – Convert from Hebrew to Gregorian date
• hd=25 – Hebrew day of month
• hy=5749 – Hebrew year
• hm=Kislev – Hebrew month

Month names may be specified in Hebrew or transliterated as follows:

In leap years, specifying Adar is the same as specifying Adar2. In non-leap years, all three of Adar, Adar1, and Adar2 are considered equivalent and will be interpreted as Adar.

The API is somewhat lenient in what it accepts for Hebrew month names. You can specify sh%27vat or Sh%27vat or Shvat. It will always consistently generate Sh'vat in the response. Generally the API will accept month names with as few as 2 characters, as this is sufficient to disambiguate them from each other,.

Similarly, the API accepts all of Adar1, Adar 1, Adar I, Adar2, Adar 2, Adar II. Because the capital-i and the lowercase-L look the same in some fonts, we recommend using the numerals 1 and 2 in the API usage. In the generated responses, Hebcal always uses Adar I and Adar II for consistency and compatibility as we’ve done for over 20 years.

4. Hebrew to Gregorian – range of dates

To convert a batch of Hebrew dates to Gregorian dates, use the same URL format as the “Hebrew to Gregorian – single date” above, and add an additional ndays parameter.

https://www.hebcal.com/converter?cfg=json&hy=5749&hm=Kislev&hd=25&h2g=1&ndays=90&strict=1

• ndays=90 – calculate range of of days (between 2 and 180 inclusive)

5. Other API notes

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

Note also an optional callback parameter:

• callback=function – wraps the JSON output text in parentheses and a function name of your choosing. Callback function names may only use upper and lowercase alphabetic characters (A-Z, a-z), numbers (0-9), the period (.), the underscore (_).

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

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.

6. Sample output in JSON and XML

{
  "gy": 2011,
  "gm": 6,
  "gd": 2,
  "afterSunset": false,
  "hy": 5771,
  "hm": "Iyyar",
  "hd": 29,
  "hebrew": "כ״ט בְּאִיָיר תשע״א",
  "heDateParts": {
    "y": "תשע״א",
    "m": "אייר",
    "d": "כ״ט"
  },
  "events": [
    "Parashat Nasso",
    "44th day of the Omer"
  ]
}

<?xml version="1.0" ?>
<hebcal>
  <gregorian year="2011" month="6" day="2" />
  <hebrew year="5771" month="Iyyar" day="29" str="כ״ט בְּאִיָיר תשע״א" />
</hebcal>

7. Sample output (batch API)

{
  "start": "2021-12-29",
  "end": "2022-01-04",
  "locale": "en",
  "hdates": {
    "2021-12-29": {
      "hy": 5782,
      "hm": "Tevet",
      "hd": 25,
      "hebrew": "כ״ה בְּטֵבֵת תשפ״ב",
      "heDateParts": {
        "y": "תשפ״ב",
        "m": "טבת",
        "d": "כ״ה"
      },
      "events": [
        "Parashat Vaera"
      ]
    },
    "2021-12-30": {
      "hy": 5782,
      "hm": "Tevet",
      "hd": 26,
      "hebrew": "כ״ו בְּטֵבֵת תשפ״ב",
      "heDateParts": {
        "y": "תשפ״ב",
        "m": "טבת",
        "d": "כ״ו"
      },
      "events": [
        "Parashat Vaera"
      ]
    },
    "2021-12-31": {
      "hy": 5782,
      "hm": "Tevet",
      "hd": 27,
      "hebrew": "כ״ז בְּטֵבֵת תשפ״ב",
      "heDateParts": {
        "y": "תשפ״ב",
        "m": "טבת",
        "d": "כ״ז"
      },
      "events": [
        "Parashat Vaera"
      ]
    },
    "2022-01-01": {
      "hy": 5782,
      "hm": "Tevet",
      "hd": 28,
      "hebrew": "כ״ח בְּטֵבֵת תשפ״ב",
      "heDateParts": {
        "y": "תשפ״ב",
        "m": "טבת",
        "d": "כ״ח"
      },
      "events": [
        "Shabbat Mevarchim Chodesh Sh'vat",
        "Parashat Vaera"
      ]
    },
    "2022-01-02": {
      "hy": 5782,
      "hm": "Tevet",
      "hd": 29,
      "hebrew": "כ״ט בְּטֵבֵת תשפ״ב",
      "heDateParts": {
        "y": "תשפ״ב",
        "m": "טבת",
        "d": "כ״ט"
      },
      "events": [
        "Parashat Bo"
      ]
    },
    "2022-01-03": {
      "hy": 5782,
      "hm": "Sh'vat",
      "hd": 1,
      "hebrew": "א׳ בִּשְׁבָט תשפ״ב",
      "heDateParts": {
        "y": "תשפ״ב",
        "m": "שבט",
        "d": "א׳"
      },
      "events": [
        "Rosh Chodesh Sh'vat",
        "Parashat Bo"
      ]
    },
    "2022-01-04": {
      "hy": 5782,
      "hm": "Sh'vat",
      "hd": 2,
      "hebrew": "ב׳ בִּשְׁבָט תשפ״ב",
      "heDateParts": {
        "y": "תשפ״ב",
        "m": "שבט",
        "d": "ב׳"
      },
      "events": [
        "Parashat Bo"
      ]
    }
  }
}