# Jewish Calendar API
> The Jewish calendar as an API — powered by Hebcal. Convert any date between the Gregorian and Hebrew calendars (with the formatted Hebrew date and the Jewish events falling on that day), list the Jewish holidays of any year — major and minor festivals, Rosh Chodesh and special Shabbatot — each with its English and Hebrew name, date and category, and get this week's Shabbat candle-lighting time, Torah portion (parashah) and Havdalah time for any location by GeoNames id or coordinates. From Rosh Hashanah and Yom Kippur to Passover, Shavuot and Hanukkah, with Hebrew dates rendered in Hebrew script, it is ideal for calendar, scheduling, event, religious and cultural applications. A Jewish-calendar resource — distinct from secular public-holiday and Islamic prayer-time APIs. Open data from Hebcal (CC-BY 4.0 / GPL).

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/hebcal-api/..."
```

## Pricing
- **Free** (Free) — 2,900 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 57,000 calls/Mo, 8 req/s
- **Pro** ($23/Mo) — 265,000 calls/Mo, 20 req/s
- **Mega** ($61/Mo) — 930,000 calls/Mo, 50 req/s

## Endpoints

### Jewish Calendar

#### `GET /v1/convert` — Convert Gregorian <-> Hebrew date

**Parameters:**
- `gy` (query, optional, string) — Gregorian year (with gm, gd) Example: `2025`
- `gm` (query, optional, string) — Gregorian month 1-12 Example: `6`
- `gd` (query, optional, string) — Gregorian day 1-31 Example: `1`
- `hy` (query, optional, string) — Hebrew year (with hm, hd) for reverse
- `hm` (query, optional, string) — Hebrew month name or number
- `hd` (query, optional, string) — Hebrew day 1-30

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hebcal-api/v1/convert?gy=2025&gm=6&gd=1"
```

**Response:**
```json
{
    "data": {
        "events": [
            "Erev Shavuot",
            "Parashat Nasso",
            "49th day of the Omer"
        ],
        "hebrew": {
            "day": 5,
            "year": 5785,
            "month": "Sivan",
            "display": "ה׳ בְּסִיוָן תשפ״ה"
        },
        "gregorian": {
            "day": 1,
            "year": 2025,
            "month": 6
        }
    },
    "meta": {
        "timestamp": "2026-06-01T16:22:55.640Z",
        "request_id": "bda466a0-76c6-4260-85a6-4faf5e246d95"
    },
    "status": "ok",
    "message": "Date converted",
    "success": true
}
```

#### `GET /v1/holidays` — Jewish holidays for a year

**Parameters:**
- `year` (query, optional, string) — Gregorian year Example: `2025`
- `month` (query, optional, string) — Optional month 1-12

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hebcal-api/v1/holidays?year=2025"
```

**Response:**
```json
{
    "data": {
        "year": 2025,
        "count": 90,
        "holidays": [
            {
                "date": "2025-01-01",
                "title": "Chanukah: 8 Candles",
                "hebrew": "חנוכה: ח׳ נרות",
                "subcat": "major",
                "category": "holiday",
                "description": "Hanukkah, the Jewish festival of rededication. Also known as the Festival of Lights, the eight-day festival is observed by lighting the candles of a hanukkiah (menorah)"
            },
            {
                "date": "2025-01-01",
                "title": "Rosh Chodesh Tevet",
                "hebrew": "ראש חודש טבת",
                "subcat": null,
                "category": "roshchodesh",
                "description": "Start of month of Tevet on the Hebrew calendar. Tevet (טֵבֵת) is the 4th month of the civil Hebrew year and the 10th month of the biblical Hebrew year. It has 29 days and corresponds to December or January on the Gregorian calendar. רֹאשׁ חוֹדֶשׁ, transliterated Rosh Chodesh or Rosh Hodesh, is a minor holiday that occurs at the beginning of every month in the Hebrew calendar. It is marked by the birth of a new moon"
            },
            {
                "date": "2025-01-02",
                "title": "Chanukah: 8th Day",
                "hebrew": "חנוכה: יום ח׳",
                "subcat": "major",
                "category": "holiday",
                "description": "Hanukk
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/shabbat` — Candle-lighting, parashah & Havdalah

**Parameters:**
- `geonameid` (query, optional, string) — A GeoNames id Example: `281184`
- `lat` (query, optional, string) — Latitude (with lon + tzid)
- `lon` (query, optional, string) — Longitude (with lat + tzid)
- `tzid` (query, optional, string) — IANA timezone (with lat/lon)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hebcal-api/v1/shabbat?geonameid=281184"
```

**Response:**
```json
{
    "data": {
        "items": [
            {
                "date": "2026-06-05T19:01:00+03:00",
                "title": "Candle lighting: 19:01",
                "category": "candles"
            },
            {
                "date": "2026-06-06",
                "title": "Parashat Sh’lach",
                "category": "parashat"
            },
            {
                "date": "2026-06-06T20:24:00+03:00",
                "title": "Havdalah: 20:24",
                "category": "havdalah"
            }
        ],
        "havdalah": {
            "title": "Havdalah: 20:24",
            "datetime": "2026-06-06T20:24:00+03:00"
        },
        "location": "Jerusalem, Israel",
        "parashah": {
            "date": "2026-06-06",
            "title": "Parashat Sh’lach",
            "hebrew": "פרשת שלח־לך"
        },
        "candle_lighting": {
            "title": "Candle lighting: 19:01",
            "datetime": "2026-06-05T19:01:00+03:00"
        }
    },
    "meta": {
        "timestamp": "2026-06-01T16:22:55.965Z",
        "request_id": "017d5b8a-2b3d-4a48-a309-a5b719915d51"
    },
    "status": "ok",
    "message": "Shabbat times retrieved",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Endpoint catalogue, months & notes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hebcal-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Hebcal is the Jewish calendar as an API. /v1/convert?gy=2025&gm=6&gd=1 converts a Gregorian date to the Hebrew calendar (returning the Hebrew year, month, day, the formatted Hebrew date and any Jewish events that day); or /v1/convert?hy=5785&hm=Sivan&hd=5 converts a Hebrew date back to Gregorian (hm accepts a Hebrew month name — Nisan, Iyyar, Sivan, … Adar1/Adar2 — or a number). /v1/holidays?year=2025 lists the Jewish holidays of a year (major and minor, plus rosh chodesh and special shabbatot), each with its English and Hebrew title, date and category; add month=6 to scope to one Gregorian month. /v1/shabbat?geonameid=281184 gives this week's Shabbat candle-lighting time, Torah portion (parashah) and Havdalah time for a location — pass a GeoNames id, or latitude + longitude + tzid (e.g. lat=40.7&lon=-74.0&tzid=America/New_York). Data from Hebcal (CC-BY 4.0 / GPL). A Jewish-calendar resource — distinct from secular public-holiday and Islamic prayer-time APIs. Ideal for calendar, scheduling, religious and cultural applications.",
        "source": "Hebcal — Jewish Calendar (hebcal.com)",
        "endpoints": [
            "/v1/convert",
            "/v1/holidays",
            "/v1/shabbat",
            "/v1/meta"
        ],
        "hebrew_months": [
            "Nisan",
            "Iyyar",
            "Sivan",
            "Tamuz",
            "Av",
            "Elul",
            "Tishrei",
            "Cheshvan",
            "Kis
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/hebcal-api
OpenAPI spec: https://www.oanor.com/api/hebcal-api/openapi.json