名称: shabbat-times 描述: 通过 Hebcal API 访问犹太日历数据和 Shabbat 时间。当构建包含 Shabbat 时间、犹太假日、Hebrew 日期或 Zmanim 的应用时使用。触发词：Shabbat 时间、Hebcal、犹太日历、Hebrew 日期、Zmanim。

犹太日历与 Shabbat 时间

通过 Hebcal API 访问 Shabbat 时间和犹太日历数据。

快速开始

// 获取某个位置的 Shabbat 时间
const response = await fetch(
  'https://www.hebcal.com/shabbat?cfg=json&geonameid=5128581&M=on'
);
const data = await response.json();

Shabbat 时间 API

通过 GeoNames ID（推荐）

const url = new URL('https://www.hebcal.com/shabbat');
url.searchParams.set('cfg', 'json');
url.searchParams.set('geonameid', '5128581'); // 纽约
url.searchParams.set('M', 'on'); // 包含 Havdalah

const response = await fetch(url);
const data = await response.json();

// 响应
{
  "title": "Hebcal 纽约 2025 年 1 月",
  "items": [
    {
      "title": "Candle lighting: 4:28pm",
      "date": "2025-01-10T16:28:00-05:00",
      "category": "candles"
    },
    {
      "title": "Parashat Shemot",
      "date": "2025-01-11",
      "category": "parashat"
    },
    {
      "title": "Havdalah: 5:31pm", 
      "date": "2025-01-11T17:31:00-05:00",
      "category": "havdalah"
    }
  ]
}

通过坐标

const url = new URL('https://www.hebcal.com/shabbat');
url.searchParams.set('cfg', 'json');
url.searchParams.set('latitude', '32.0853');
url.searchParams.set('longitude', '34.7818');
url.searchParams.set('tzid', 'Asia/Jerusalem');

犹太日历 API

const url = new URL('https://www.hebcal.com/hebcal');
url.searchParams.set('cfg', 'json');
url.searchParams.set('v', '1');
url.searchParams.set('year', '2025');
url.searchParams.set('month', 'x'); // 所有月份

// 可选参数
url.searchParams.set('maj', 'on'); // 主要假日
url.searchParams.set('min', 'on'); // 次要假日
url.searchParams.set('mod', 'on'); // 现代假日
url.searchParams.set('nx', 'on');  // Rosh Chodesh
url.searchParams.set('ss', 'on');  // 特殊 Shabbatot
url.searchParams.set('s', 'on');   // 每周 parsha

const response = await fetch(url);
const holidays = await response.json();

Hebrew 日期转换

// 格里高利历转 Hebrew
const url = new URL('https://www.hebcal.com/converter');
url.searchParams.set('cfg', 'json');
url.searchParams.set('gy', '2025');
url.searchParams.set('gm', '1');
url.searchParams.set('gd', '15');

const response = await fetch(url);
const data = await response.json();
// { "hy": 5785, "hm": "Tevet", "hd": 15, "hebrew": "ט״ו בטבת תשפ״ה" }

React Hook

import { useState, useEffect } from 'react';

interface ShabbatTimes {
  candleLighting: Date | null;
  havdalah: Date | null;
  parsha: string | null;
}

function useShabbatTimes(geonameid: string) {
  const [times, setTimes] = useState<ShabbatTimes | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function fetchTimes() {
      const url = new URL('https://www.hebcal.com/shabbat');
      url.searchParams.set('cfg', 'json');
      url.searchParams.set('geonameid', geonameid);
      url.searchParams.set('M', 'on');

      const response = await fetch(url);
      const data = await response.json();

      const result: ShabbatTimes = {
        candleLighting: null,
        havdalah: null,
        parsha: null
      };

      for (const item of data.items) {
        if (item.category === 'candles') {
          result.candleLighting = new Date(item.date);
        } else if (item.category === 'havdalah') {
          result.havdalah = new Date(item.date);
        } else if (item.category === 'parashat') {
          result.parsha = item.title.replace('Parashat ', '');
        }
      }

      setTimes(result);
      setLoading(false);
    }

    fetchTimes();
  }, [geonameid]);

  return { times, loading };
}

常见 GeoNames ID

城市	GeoNames ID
耶路撒冷	281184
特拉维夫	293397
纽约	5128581
洛杉矶	5368361
伦敦	2643743
巴黎	2988507

资源

Hebcal API 文档: https://www.hebcal.com/home/developer-apis