Breaking change in REST API (missing year in 'hebrew' field)

JustAUser 2 months ago updated by Michael J. Radwin 1 month ago 4

About a year ago I started using the hebcal.com/hebcal REST API, and on the hebrew field I got the day, the month, and the year. I.e. ה' באייר תש"ח.

Today I see that on the hebrew field I get only the day and the month, without the year, like ה' באייר.

(Only on very special days I get the year, like in Rosh Hashana א' בתשרי תשע"ד.)

This is a breaking change, isn't it?

Now nowhere on the response I get the hebrew year directly.

Example of API call params:

const params = new URLSearchParams({
        year: '' + year,
        month: '' + month,
        v: '1',
        cfg: 'json',
        maj: 'on', /* major holidays */
        min: 'on', /* minor holidays */
        mod: 'on',
        mf: 'on',
        d: 'on',
        i: 'on',
        lg: 'he', /* language */
    const req = await fetch(

Wow, that was quick, although I already implemented a Gimatriya code to convert the year from hdate field :D

Regarding changing the API:

On automated systems this is considered a breaking change (if a validation is done on the returned structure, now it has an unexpected new field). I would, at least, control adding this new field via query params and not automatically. (like &fields[]=category&fields[]=hebrew&fields[]=heDateParts, and if fields query param is omitted just return some default fields).

Just my 2 cents.

Thanks, I'm going to look at it and also take a look at the JS package.


It was straightforward to add the "heDateParts" field to our regular Jewish calendar REST API as well. We've done so already as adding additional fields doesn't break existing clients. Let us know if this will fix the problem for you?

Under review

Hi, thanks for using Hebcal APIs.

Yes, you are correct, this is a breaking change. We're sorry for any inconvenience caused.

If you're only looking for Hebrew date information, you can get the Hebrew year in an easy-to-parse format using this API (note the "heDateParts" field).


If you're working in JavaScript, which you appear to be from the code example above, you can avoid the latency of using a web API at all and just use the native implementation of HDate and HebrewCalendar from the @hebcal/core JavaScript package