canonical: https://jentic.com/apis/hebcal.com/hebcal

# Hebcal API

Jentic publishes the only available OpenAPI specification for Hebcal API, keeping it validated and agent-ready. The Hebcal API is a Jewish calendar service that returns holiday calendars, Shabbat candle-lighting and havdalah times, halachic times (zmanim), Hebrew/Gregorian date conversion, yahrzeit and anniversary calculations, and Torah leyning data. All endpoints are public read-only GETs requiring no authentication, and responses are JSON keyed off location and date parameters. The service does not write to user calendars or accept event submissions.

## For AI agents

Compute Jewish holiday calendars, Shabbat times, zmanim, Hebrew date conversions, and yahrzeit dates across 6 unauthenticated endpoints.

## Scope

Does not write to user calendars, send notifications, or accept event submissions - use for read-only Jewish calendar, zmanim, and date-conversion lookups only.

## Capabilities

- Generate a Jewish holiday calendar for a given year and location via /hebcal
- Look up Shabbat candle-lighting and havdalah times for a city or coordinates via /shabbat
- Calculate halachic times (zmanim) for any date and location via /zmanim
- Convert dates between the Hebrew and Gregorian calendars via /converter
- Compute upcoming yahrzeit and Hebrew anniversary dates from a Gregorian death/event date via /yahrzeit
- Retrieve Torah leyning details (parsha, aliyot, haftarah) for a given Shabbat or holiday via /leyning

## Use cases

### Synagogue Website Calendar

A synagogue website needs to display weekly Shabbat times and an annual holiday calendar without maintaining a Hebrew date library. The Hebcal API returns localized candle-lighting, havdalah, and holiday data keyed off city or coordinates so the site can render an accurate calendar with a single GET per page load. No API key is needed.

Example prompt: Call GET /shabbat?cfg=json&geonameid=5128581 and return this week's candle-lighting and havdalah times for New York

### Hebrew Date Conversion Tool

An app that prints bar mitzvah certificates needs to convert a child's Gregorian birthday into the Hebrew date and back. The /converter endpoint handles bidirectional conversion in a single call, including the after-sunset edge case via the gs flag.

Example prompt: Convert the Gregorian date 1990-05-14 to its Hebrew equivalent by calling GET /converter?cfg=json&gy=1990&gm=5&gd=14&g2h=1

### Zmanim and Yahrzeit Reminders

A reminder service computes daily halachic times and upcoming yahrzeit dates for users who provide their location and family records. The /zmanim and /yahrzeit endpoints return the full set of times and the next n yahrzeit occurrences in a single call, eliminating the need for in-house astronomical calculations.

Example prompt: Call GET /yahrzeit?cfg=json&years=10&type1=Yahrzeit&date1=1990-05-14 and return the next 10 yahrzeit dates

### AI Agent Jewish Calendar Assistant

An AI agent answers questions like 'when is Pesach next year in London?' or 'what's this week's parsha?' by calling Hebcal through Jentic. Because Hebcal requires no auth, the agent's only job is to pick the right operation - Jentic surfaces it by intent search.

Example prompt: Search Jentic for 'get jewish holidays for a year', load the /hebcal operation, and return the holidays for 2026 in London

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /hebcal | Get Jewish calendar events for a year and location |
| GET | /shabbat | Get Shabbat candle-lighting and havdalah times |
| GET | /zmanim | Get halachic times for a date and location |
| GET | /converter | Convert between Hebrew and Gregorian dates |
| GET | /yahrzeit | Calculate yahrzeit and anniversary dates |
| GET | /leyning | Get Torah reading details for a Shabbat or holiday |

## Key resources

- **Calendar** — Generate Jewish holiday calendars and Shabbat times by year, location, or date range
- **Zmanim** — Compute halachic times (sunrise, sunset, candle-lighting, etc.) for any location and date
- **Date Converter** — Convert dates between the Hebrew and Gregorian calendars
- **Yahrzeit** — Compute upcoming yahrzeit and Hebrew anniversary dates from a Gregorian event date
- **Leyning** — Retrieve Torah reading details for a given Shabbat or holiday

## Why Jentic

- **Setup:** The Hebcal API needs no credential, so wiring it by hand is mostly formatting query parameters like geonameid, year, and date and reconciling responses with your other tools. Through Jentic you install once, import the Hebcal API from the API Directory, and your agent calls it with a consistent request and response shape.
- **Permission scoping:** The Hebcal API is read-only and unauthenticated, with lookups spread across endpoints like /shabbat, /zmanim, and /converter, so limit the agent to the lookups it needs, such as getting Shabbat times or converting a Hebrew date. You choose the operations it may call, so anything outside that set is not included unless you add it.
- **Credential handling:** Hebcal is unauthenticated, so there is no credential to store or inject. Jentic still routes the call through your own Jentic One instance so it shares a consistent execution surface with your other tools.
- **Discovery method:** Agents search Jentic by intent such as 'get shabbat times' or 'convert a hebrew date', and Jentic returns the matching Hebcal operation with its input schema so the agent passes geonameid, year, or date directly without browsing the reference docs.

## Related APIs

- **OpenWeatherMap API** — OpenWeatherMap supplies weather data that pairs with Hebcal's location-based Shabbat and zmanim times
- **WeatherAPI** — WeatherAPI offers weather and astronomy data alongside Hebcal's Jewish-specific astronomical calculations
- **Hearthstone API** — Unrelated domain - listed only because no direct Jewish-calendar alternative is in the corpus

## FAQ

### Why is there no official OpenAPI spec for Hebcal API?

Hebcal publishes documentation on hebcal.com but does not ship an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Hebcal via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Hebcal API use?

The Hebcal API requires no authentication - all six endpoints are public GETs. Through Jentic the agent calls them directly with no credential handling required.

### Can I get Shabbat candle-lighting times for any city with this API?

Yes. GET /shabbat accepts a geonameid, zip code, or latitude/longitude pair and returns candle-lighting and havdalah times for the upcoming Shabbat at that location.

### What are the rate limits for the Hebcal API?

Hebcal asks consumers to keep request volume reasonable; there is no published per-key quota since the API is unauthenticated. For sustained or high-volume use, cache responses by date+location since the underlying data only changes daily.

### How do I get this week's Shabbat times through Jentic?

Run pip install jentic, have the agent search for 'get shabbat candle lighting times', load the /shabbat operation, and execute it with a geonameid or lat/lon for the user's city.

### Does the Hebcal API include Torah reading information?

Yes. GET /leyning returns the parsha, aliyot breakdown, and haftarah for a given Shabbat or holiday, which is useful for synagogue calendars and study apps.

### Can I limit what my agent is allowed to do with the Hebcal API?

Yes. Because you run Jentic One yourself, you decide which Hebcal operations your agent may call, so you can allow just the lookups it needs, such as GET /shabbat for candle-lighting times or GET /converter for Hebrew date conversion, while withholding /zmanim, /yahrzeit, or /leyning. Anything outside the set you import is not available to the agent unless you add it. Since the Hebcal API is read-only and unauthenticated, there are no credentials to scope, only the operations you expose.