Hebcal API

Free Hebrew calendar API with no key: convert Gregorian to Hebrew dates and back, plus Jewish holidays, Shabbat times, Torah portions and yahrzeit calculations. Tested example included.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the Hebcal API?

Hebcal is a free, key-free API for the Hebrew calendar. It converts dates between the Gregorian and Hebrew calendars in both directions, and provides Jewish holiday dates, Shabbat candle-lighting times by location, weekly Torah portions and yahrzeit anniversary calculations.

The Hebrew calendar is genuinely difficult to implement: it is lunisolar, months have variable length, leap years add an entire thirteenth month on a nineteen-year cycle, and the day begins at sunset rather than midnight. Hebcal has been maintaining a correct implementation since 1994 and exposes it as a free API, which is a far better idea than writing your own conversion.

That sunset boundary is the detail that catches every newcomer. A Hebrew date changes at nightfall, not at midnight, so the same Gregorian day maps to two different Hebrew dates depending on the time — which is why the API takes an `afterSunset` flag and echoes it back in the response. Get that wrong and holiday dates land a day out. The response also includes the `events` array, which surfaces the weekly Torah portion and any holidays falling on that date without a second request.

Quick facts

Base URL: https://www.hebcal.com
Authentication: No API key or account. Hebcal is a long-running non-profit project and asks only for attribution.
Rate limit: No hard limit published; reasonable use expected. Calendar data is deterministic, so cache it indefinitely.
Pricing: Free. The underlying library is open source under GPL.
CORS: Enabled — callable directly from browser JavaScript
Official docs: Read the docs

How to use the Hebcal API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Convert a Gregorian date to the Hebrew calendar

GET https://www.hebcal.com/converter?cfg=json&gy=2026&gm=8&gd=21&g2h=1

curl

curl 'https://www.hebcal.com/converter?cfg=json&gy=2026&gm=8&gd=21&g2h=1'

JavaScript (fetch)

const res = await fetch("https://www.hebcal.com/converter?cfg=json&gy=2026&gm=8&gd=21&g2h=1");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://www.hebcal.com/converter?cfg=json&gy=2026&gm=8&gd=21&g2h=1", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200

{
  "gy": 2026,
  "gm": 8,
  "gd": 21,
  "afterSunset": false,
  "hy": 5786,
  "hm": "Elul",
  "hd": 8,
  "hebrew": "ח׳ בֶּאֱלוּל תשפ״ו",
  "heDateParts": {
    "y": "תשפ״ו",
    "m": "אלול",
    "d": "ח׳"
  },
  "events": [
    "Parashat Ki Teitzei"
  ]
}

Parameters

Parameter	Type	Required	Description
`cfg`	query	Required	Output format. `json` is required; the endpoint can also emit other formats. `json`
`gy / gm / gd`	query	Optional	Gregorian year, month and day when converting to Hebrew. `2026`
`g2h`	query	Optional	Set to 1 for Gregorian-to-Hebrew conversion. Use `h2g=1` for the reverse. `1`
`hy / hm / hd`	query	Optional	Hebrew year, month name and day when converting back to Gregorian. `5786`
`gs`	query	Optional	Set to `on` when the time is after sunset — the Hebrew date advances at nightfall, not midnight. `on`
`(shabbat)`	path segment	Optional	The `/shabbat` endpoint returns candle-lighting and havdalah times for a geographic location.

Response fields

gy / gm / gdinteger: The Gregorian date, echoed back.
afterSunsetboolean: Whether the conversion treated the time as after nightfall. This is the single most important field to get right.
hyinteger: Hebrew year, for example 5786.
hmstring: Hebrew month name transliterated — Elul, Tishrei, Nisan. Note that leap years insert Adar I and Adar II.
hdinteger: Day of the Hebrew month.
hebrewstring: The full date rendered in Hebrew script with vowel points, ready to display.
heDatePartsobject: The Hebrew year, month and day as separate Hebrew-script strings, for custom formatting.
eventsarray: Holidays and the weekly Torah portion falling on that date, so you get them without a second call.

What you can build with the Hebcal API

Add Hebrew dates alongside Gregorian ones in a calendar application
Calculate yahrzeit (memorial) anniversaries correctly across leap years
Show Shabbat candle-lighting and havdalah times for a user's location
Display the weekly Torah portion on a synagogue or community site

Common errors and how to fix them

400

Missing or malformed date components.

Fix: Gregorian conversion needs `gy`, `gm`, `gd` and `g2h=1` together. Hebrew month names in `hm` must use Hebcal's transliteration.

Date is one day out

The `gs` sunset flag was not set.

Fix: The Hebrew day starts at nightfall. If your timestamp is in the evening, pass `gs=on` — this is the most common bug in Hebrew calendar code.

Unexpected month in a leap year

Leap years contain Adar I and Adar II.

Fix: Seven years in every nineteen have a thirteenth month. Do not assume twelve months when iterating a Hebrew year.

Hebcal API — frequently asked questions

Is the Hebcal API free?

Yes, free with no API key or account. Hebcal is a long-running non-profit project, its underlying library is open source, and it asks only for attribution.

Why is my converted date one day off?

Almost certainly the sunset boundary. The Hebrew day begins at nightfall rather than midnight, so an evening timestamp belongs to the next Hebrew date. Pass `gs=on` and check the `afterSunset` field in the response.

Does the Hebrew calendar have leap years?

Yes, but they work differently — seven years in every nineteen gain an entire extra month, Adar I, with the regular Adar becoming Adar II. Code that assumes twelve months per year will break on those years.

Can I get Shabbat times for a specific city?

Yes. The `/shabbat` endpoint returns candle-lighting and havdalah times for a geographic location, since both depend on local sunset and therefore on latitude and longitude.

Tools that pair with this API

Timestamp Converter

Convert timestamps to human-readable dates and dates back to timestamps. Auto-detects seconds vs milliseconds, shows local, UTC and ISO 8601 formats.

Date Difference Calculator

Calculate the exact difference between two dates in years, months and days, plus total days, weeks, hours and minutes. Free, fast and private.

Time Zone Converter

Convert any date and time between world time zones. See UTC offsets, daylight saving handled automatically, and compare multiple zones at once.

Hebcal is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.