Calendar REST API fails out of season if Omer count is turned on

Monica Cellio 2 weeks ago updated 2 weeks ago 4

We use the REST API to add the Hebrew date to our site.  We added this integration during the Omer and included o=on in the URL.  We're fetching data a month a time, so we've only now (June 1) encountered this failure: if the URL includes o=on "out of season", the API returns the wrong month's data.  We expected this directive to just be ignored outside of the Omer.

Specifically, this URL returns data for May, not June:


Dropping "&o=on" causes the current month's data to be returned.

Would it be possible for the API to ignore the Omer directive when not relevant?  We'd like to be able to embed one durable URL, without having to remember to edit it at the beginning and end of the Omer each year.


Hi, thanks for using Hebcal. Sorry to hear about the difficulty with the API.

It turns out the issue you're seeing is actually due to caching, and not due to the &o=on parameter. When you specify cfg=json, the results are cached for 24 hours. We set a 24-hour expiry to reduce load on our servers and to speed up the results for clients. However, depending on where you are on the planet, today is either June 1 or May 31.

Note the age header below:

Michaels-MBP:~ mradwin$ curl --compressed -v 'https://www.hebcal.com/hebcal?v=1&cfg=json&year=now&month=now&d=on&o=on' | jq .title
> GET /hebcal?v=1&cfg=json&year=now&month=now&d=on&o=on HTTP/2
> Host: www.hebcal.com
> User-Agent: curl/7.54.0
> Accept: */*
> Accept-Encoding: deflate, gzip
< HTTP/2 200 
< server: nginx/1.18.0 (Ubuntu)
< date: Tue, 01 Jun 2021 15:44:10 GMT
< content-type: application/json; charset=utf-8
< content-length: 835
< vary: Accept-Encoding
< etag: W/"d9-CQGoPjGBqbw/ZdAoggDClB0DGFA"
< last-modified: Sun, 30 May 2021 22:46:51 GMT
< cache-control: max-age=86400
< content-encoding: gzip
< x-response-time: 3.875ms
< x-varnish: 37561102 34898242
< age: 61543
< via: 1.1 varnish (Varnish/6.2)
< access-control-allow-origin: *
< accept-ranges: bytes
"Hebcal Diaspora May 2021"
Michaels-MBP:~ mradwin$ curl --compressed -v 'https://www.hebcal.com/hebcal?v=1&cfg=json&year=now&month=now&d=on&o=on' | jq .title

In approximately 7 hours the cache will expire and you'll get the results for June 1.

If you specify the exact month and year (for example https://www.hebcal.com/hebcal?v=1&cfg=json&year=2021&month=6&d=on&o=on ) you will see that although &o=on is specified, you'll correctly get the June 2021 events.

In the future, I think we could safely reduce the cache from 24 hours to 4 hours when year=now and/or month=now to improve the coherency of the results without a significant impact on the user experience.

Oh!  I didn't consider caching.  So the reason it worked without the parameter isn't that the parameter has an issue but that I hadn't previously queried that exact URL so there was nothing cached.

Thanks for the tip about using the exact year and month, which we could get from the environment and then send.  That said, a shorter cache would probably help too. :-)

Thanks for the info and the quick response.


OK, we've adjusted the cache time down to 3 hours when year=now and/or month=now, but actually increased it from 24 hours to 7 days when there's a user-specified year and/or month. This should fix your problem (within maximum 3 hours of the month flipping over) and still be good for our server and neetwork load.

Sounds great, thanks!  When there's a user-specified year and month I would hope the data isn't changing much and so a long cache should be fine there. :-)