זמני שבת וחג, כקבצים פשוטים

1. התחלה מהירה

בוחרים מזהה עיר (slug) מתוך /v1/cities.json (למשל jerusalem, new-york, london) ומורידים את חלונות המנוחה שלה:

curl https://api.zmanim.cc/v1/jerusalem/windows.json

const res = await fetch("https://api.zmanim.cc/v1/jerusalem/windows.json");
const { windows } = await res.json();
const now = Date.now() / 1000;
const next = windows.find((w) => (w.end_ts ?? w.start_ts + 4 * 86400) > now);
console.log(next.title.he, next.start, next.end);

התשובה, מקוצרת לחלון אחד:

{
  "api_version": 1,
  "data_version": "dbef44f6582f",
  "rounding": {
    "entry": "floor_minute",
    "exit": "engine_minute",
    "stable": false,
    "note": "Candle lighting and every other zman are truncated to the minute, exactly as zmanim.cc displays them, except the exit times, which are the engine minute: havdalah (8.5 degrees) and tzeit hakochavim are rounded up to the next minute, and Rabbeinu Tam is sunset rounded to the nearest minute plus 72 minutes. A pending rabbinic ruling may move exit minutes by 1; such a change is not a breaking change."
  },
  "docs_url": "https://api.zmanim.cc/",
  "disclaimer_url": "https://api.zmanim.cc/#terms",
  "city": {
    "slug": "jerusalem",
    "name": {
      "he": "ירושלים",
      "en": "Jerusalem"
    },
    "country": "Israel",
    "lat": 31.7683,
    "lng": 35.2137,
    "elevation_m": 754,
    "tz": "Asia/Jerusalem",
    "il": true,
    "candle_minutes": 40,
    "candle_basis": "elevation"
  },
  "coverage": {
    "from_year": 2026,
    "to_year": 2046
  },
  "windows": [
    {
      "id": "2026-10-02-shmini-atzeret",
      "kind": "shabbat_yomtov",
      "title": {"he":"שמיני עצרת (שמחת תורה) + שבת","en":"Shmini Atzeret (Simchat Torah) + Shabbat"},
      "start": "2026-10-02T17:47:00+03:00",
      "start_ts": 1790952420,
      "end": "2026-10-03T18:58:00+03:00",
      "end_ts": 1791043080,
      "start_reason": null,
      "end_reason": null
    },
    ...
  ]
}

2. הקבצים

• HTTPS בלבד, GET/HEAD, CORS פתוח (Access-Control-Allow-Origin: *). UTF-8, דחוס לפי בקשה.
• כל תשובת JSON מתחילה ב-api_version, data_version, rounding, docs_url, disclaimer_url; קובצי עיר ממשיכים באובייקט city כמו ב-cities.json.
• חלון נמצא בקובץ השנה של יום המנוחה האחרון שלו, כך שקובצי השנים יחד שווים ל-windows.json. קיימות רק השנים שב-year_files של index.json (היום 2026 עד 2028); לקוח לטווח ארוך ישתמש ב-windows.json.
• כל מפתח קיים תמיד; ערך שאינו קיים הוא null. מפתחות חדשים עשויים להתווסף; מתעלמים ממה שלא מכירים.
• slug לא נמחק לעולם. כפילות מופנית ב-301 ל-slug שנשאר (למשל kiryat-sefer → modiin-illit); יש לעקוב אחרי הפניות.
• ערכי epoch עוברים את 2³¹ ב-2038: להשתמש ב-uint32_t או ב-64 סיביות, לא ב-time_t חתום של 32 סיביות.

3. נקודת הקצה היומית

/v1/{city}/{YYYY-MM-DD}.json נותנת את כל הזמנים של יום אזרחי אחד, 1900 עד 2100: alot_hashachar, misheyakir, sunrise, sof_zman_shma_mga/_gra, sof_zman_tfilla_mga/_gra, chatzot, mincha_gedola_gra/_mga, mincha_ketana_gra/_mga, plag_hamincha, candle_lighting, sunset, tzeit_hakochavim, havdalah, rabbeinu_tam, chatzot_layla, לכל אחד גם _ts. יש בה גם תאריך עברי, חגים, פרשה, ו-rest/next_rest (חלונות מלאים). הזריחה והשקיעה בגובה פני הים; candle_lighting קיים רק בערב שמדליקים בו לפני השקיעה; havdalah רק ביום האחרון של חלון.

דוגמה, /v1/jerusalem/2026-10-16.json (מקוצר):

{
  "api_version": 1,
  ...
  "date": "2026-10-16",
  "day_of_week": 5,
  "hebrew_date": {"he":"ה׳ חשוון תשפ״ז","day":5,"month":"Cheshvan","month_num":8,"year":5787},
  "is_shabbat": false,
  "is_yomtov": false,
  "parasha": {"id":"noach","he":"נח","en":"Noach"},
  "zmanim": {
    "sunrise": "2026-10-16T06:42:00+03:00",
    "sunrise_ts": 1792122120,
    "candle_lighting": "2026-10-16T17:30:00+03:00",
    "candle_lighting_ts": 1792161000,
    "sunset": "2026-10-16T18:06:00+03:00",
    "sunset_ts": 1792163160,
    "tzeit_hakochavim": "2026-10-16T18:27:00+03:00",
    "tzeit_hakochavim_ts": 1792164420,
    "havdalah": null,
    "havdalah_ts": null,
    ...
  },
  "rest": {"id": "2026-10-16-shabbat", "start": "2026-10-16T17:30:00+03:00", "end": "2026-10-17T18:42:00+03:00", ...},
  "next_rest": {...}
}

בניגוד לקבצים, היא מחושבת לפי בקשה ונשמרת בקצה הרשת ליום. היא רצה על תוכנית חינמית עם 100,000 בקשות ביום, משותפות לכל המשתמשים. משתמשים בה לזמני היום, בקשה אחת לעיר ליום, ולעולם לא בלולאה על תאריכים: כל מה שנוגע לשבת וחג נמצא בקבצים הסטטיים.

4. מושגי יסוד

חלונות מנוחה

חלון הוא פרק זמן רציף אחד שאסור בו במלאכה, מהדלקת הנרות בערב ועד היציאה (הבדלה, 8.5°) של יום המנוחה האחרון. kind הוא shabbat, yomtov, shabbat_yomtov (צמודים, בכל סדר, 2 או 3 ימים), yomkippur או shabbat_yomkippur; ערך לא מוכר מתייחסים אליו כמנוחה. id (תאריך הערב ותווית) ייחודי לעיר ויציב, מתאים כמפתח במסד נתונים.

מכשיר שנכבה בהבדלה של מוצאי שבת היה שובר את ראש השנה 2026, שמתחיל בליל שבת: בקרני שומרון נחים משישי עד מוצאי ראשון, חלון אחד. קובץ השנה מראה את הפירוט: ימי המנוחה days[] וההדלקה בכל ערב lighting[] (before_sunset, או from_existing_flame אחרי שעה מסוימת):

{
  "id": "2026-09-11-rosh-hashana",
  "kind": "shabbat_yomtov",
  "title": {"he":"ראש השנה + שבת","en":"Rosh Hashana + Shabbat"},
  "erev": "2026-09-11",
  "start": "2026-09-11T18:29:00+03:00",
  "start_ts": 1789140540,
  "start_reason": null,
  "end": "2026-09-13T19:26:00+03:00",
  "end_ts": 1789316760,
  "end_reason": null,
  "days": [
    {"date":"2026-09-12","kind":"shabbat_yomtov","holiday":{"id":"rosh-hashana-1","he":"ראש השנה א׳","en":"Rosh Hashana I"},"parasha":null},
    {"date":"2026-09-13","kind":"yomtov","holiday":{"id":"rosh-hashana-2","he":"ראש השנה ב׳","en":"Rosh Hashana II"},"parasha":null}
  ],
  "lighting": [
    {"date":"2026-09-11","type":"before_sunset","at":"2026-09-11T18:29:00+03:00","at_ts":1789140540,"after":null,"after_ts":null,"reason":null,"existing_flame":false},
    {"date":"2026-09-12","type":"from_existing_flame","at":null,"at_ts":null,"after":"2026-09-12T19:27:00+03:00","after_ts":1789230420,"reason":null,"existing_flame":true}
  ]
}

אינם חלונות מנוחה: חול המועד, פורים, חנוכה, תשעה באב והצומות הקלים.

מנהג העיר

הדלקת הנרות הולכת לפי מנהג כל עיר, ולכן ה-API עובד לפי עיר ולא לפי קואורדינטות. candle_minutes הוא מספר הדקות לפני השקיעה (ירושלים 40, חיפה 30, תל אביב 22, ניו יורק 18). candle_basis אומר מאיזו שקיעה: sea_level, elevation (של העיר עצמה, למשל ירושלים) או jerusalem (פתח תקווה מדליקה כשירושלים מדליקה). il בוחר בין לוח ארץ ישראל לחו״ל: אורך יום טוב, הפרשה, ו-tzeit_hakochavim היומי (שקיעה ועוד 20 דקות בארץ, 6° בחו״ל). היציאה היא 8.5° בכל מקום.

זמנים: ISO ו-epoch

כל רגע מופיע פעמיים: "start": "2026-09-11T18:29:00+03:00" הוא שעון הקיר של העיר עם ההפרש שלה, כולל שעון קיץ (תווים 11 עד 16 הם ה-HH:MM להצגה), ו-"start_ts": 1789140540 הוא אותו רגע בשניות epoch של UTC, להשוואה עם השעה הנוכחית. תאריכים פשוטים (erev, days[].date) הם תאריכים אזרחיים בעיר.

עיגול ו-stable: false

הזמנים זהים למה ש-zmanim.cc מציג: הדלקת נרות וזמני היום נחתכים לדקה (rounding.entry: "floor_minute"); הבדלה וצאת הכוכבים מעוגלות למעלה, רבנו תם הוא שקיעה מעוגלת לדקה הקרובה ועוד 72 (rounding.exit: "engine_minute"). פסיקה הלכתית שממתינה עשויה להזיז דקות יציאה בדקה אחת. זה אינו שינוי שובר: משתנים רק הערכים ו-data_version. לכן בודקים את version.json פעם ביום, שומרים במכשירים מרווח של דקה לפחות בכל צד, ולא מקבעים את הזמנים במקום שאי אפשר לרענן.

ערכי null

בצפון הרחוק בקיץ השמש עשויה לא לרדת 8.5° מתחת לאופק, ואז אין זמן יציאה. ה-API לא ממציא זמן: end ו-end_ts הם null, ו-end_reason אומר למה (depression_not_reached או no_sunset). היום זה נוגע רק לסנקט פטרבורג, סביב יוני. לעולם לא לקרוא null כ"אין שבת" (ב-JavaScript now < null הוא false): קודם מחליפים אותו בגבול זהיר, כמו בהתחלה המהירה. קובצי המכשירים לא יכולים להכיל null, ולכן יש בהם ערך חלופי מסומן שנוטה לכיוון מנוחה ארוכה יותר (12:00 שעון מקומי ביום שאחרי יום המנוחה האחרון):

# 2026-05-29-shabbat: no computed end (depression_not_reached): 12:00 local on the day after - conservative placeholder, not a zman
1780080060 1780218000 shabbat

מי שמשרת עיר כזו צריך לשאול את הרב מה זמן היציאה. גם בנקודת הקצה היומית כל זמן שהשמש לא מגיעה אליו הוא null.

5. מכשירים לא מקוונים

רק מספרים, שניות epoch של UTC, בלי אזורי זמן ובלי שעון קיץ במכשיר. נחים כל עוד start <= now < end.

windows.txt, למכשיר שמתחבר לרשת

שורה start_ts end_ts kind לכל חלון; שורות # הן הערות (הכותרת כוללת data_version ו-# count:). שומרים את הקובץ בזיכרון הבזק ועובדים מהעותק, כך שהמכשיר לא צריך רשת בשבת. מקבלים הורדה רק כשהיא שלמה: HTTP 200, מספר השורות שווה ל-# count:, ובכל שורה start < end. משתמשים ב-HTTPS עם אוסף תעודות CA (לעולם לא setInsecure()) ומכוונים את השעון מ-NTP.

# zmanim.cc rest windows (Shabbat, Yom Tov, Yom Kippur): no-melacha periods
# api_version: 1
# city: karnei-shomron (Karnei Shomron)
# tz: Asia/Jerusalem (numbers below are UTC epoch seconds, no timezone math needed)
# data_version: dbef44f6582f
# coverage: 2026-2046
# count: 1184
# placeholders: 0
# rounding: start = candle lighting truncated to the minute; end = havdalah (8.5 deg), engine minute (rounded up); stable=false, an exit may move by 1 minute after a pending ruling
# docs: https://api.zmanim.cc/#txt
# format: start_ts end_ts kind   (resting while start_ts <= now < end_ts; kind = shabbat|yomtov|shabbat_yomtov|yomkippur|shabbat_yomkippur)
1767363840 1767454020 shabbat
1767969000 1768059180 shabbat
...
1789140540 1789316760 shabbat_yomtov
1789744740 1789834620 shabbat

windows.h, למכשיר שלעולם לא מתחבר

כותרת C/C++ שמהדרים לתוך הקושחה: zmanim_windows[ZMANIM_WINDOW_COUNT][2] (התחלה וסוף ב-uint32_t), zmanim_window_kinds[], ו-ZMANIM_READ_U32() שקורא מ-PROGMEM ב-AVR. כ-10 KB זיכרון בזק ל-20 שנה; נכנס ב-Arduino Uno. כוללים אותה בקובץ מקור אחד בלבד.

#define ZMANIM_DATA_VERSION "dbef44f6582f"
#define ZMANIM_CITY "karnei-shomron"
#define ZMANIM_FROM_YEAR 2026
#define ZMANIM_TO_YEAR 2046
#define ZMANIM_WINDOW_COUNT 1184

static const uint32_t zmanim_windows[ZMANIM_WINDOW_COUNT][2] ZMANIM_PROGMEM = {
  {1767363840UL, 1767454020UL},
  {1767969000UL, 1768059180UL},
  ...
};

/* 1 = resting, 0 = weekday, -1 = unknown (clock unset or table ran out: stay resting) */
int zmanim_state(uint32_t now, uint32_t margin) {
  for (uint16_t i = 0; i < ZMANIM_WINDOW_COUNT; i++) {
    uint32_t start = ZMANIM_READ_U32(&zmanim_windows[i][0]);
    uint32_t end = ZMANIM_READ_U32(&zmanim_windows[i][1]);
    if (now + margin < start) return 0;
    if (now < end + margin) return 1;
  }
  return -1;
}

סטיית שעון ורענון

• שעון זמן אמת נשמר ב-UTC, ועדיף מפוצה טמפרטורה כמו DS3231 (כדקה בשנה). DS1307 עלול לסטות 10 דקות בשנה.
• מרווח משני הצדדים (מתחילים מוקדם, מסיימים מאוחר): דקה לפסיקת העיגול, דקה לביטחון, ועוד דקה לכל שנה בין בדיקות שעון. NTP: 2 דקות; בדיקה שנתית: 3; כל 5 שנים: 7; אף פעם: כ-22.
• כשל בטוח: כשהשעון איבד מתח, לא מכוון, או שהטבלה נגמרה (אחרי ZMANIM_TO_YEAR), נשארים במצב מנוחה ומציגים זאת.
• רענון: פעם ביום, מחוץ לחלון, מורידים את version.json (כ-100 בתים) ומורידים את הקובץ מחדש רק כש-data_version השתנה. מכשיר שמתחבר אפילו פעם בשנה (ביקור שירות, אפליקציה בטלפון, USB) מקבל כל תיקון ומזיז את טווח 20 השנה קדימה.

{"api_version":1,"data_version":"dbef44f6582f","coverage":{"from_year":2026,"to_year":2046}}

6. יומן

https://api.zmanim.cc/v1/{city}/windows.ics (או webcal://) הוא יומן iCalendar עם אירוע אחד לכל חלון, מהדלקת הנרות עד היציאה, ב-UTC, מחודש אחורה עד כשנתיים קדימה. אפשר להירשם אליו ב-Google Calendar (יומנים אחרים › מכתובת URL), ביומן של Apple או ב-Outlook, או באינטגרציית Remote Calendar של Home Assistant, שישות היומן שלה on במשך כל חלון. SUMMARY הוא הכותרת בעברית ובאנגלית, UID הוא {id}@{city}.api.zmanim.cc, CATEGORIES הוא הסוג. אפליקציות יומן מתרעננות בקצב שלהן (ב-Google זה יכול לקחת יום ויותר), ולכן לא מפעילים מכשיר לפי יומן מנוי.

7. שגיאות, מטמון, גרסאות

• שגיאות הן JSON: {"error": {"code", "message", "docs"}}. קודים: invalid_date ו-date_out_of_range (400), city_not_found (404, ה-slug באותיות קטנות), not_found (404; לקובץ שנה שלא קיים ההודעה מפרטת את השנים), method_not_allowed (405), internal_error (500). אם המכסה היומית של נקודת הקצה היומית נגמרה, Cloudflare עונה בעמוד משלו: כל תשובה שאינה 200 היא "אין נתונים", וממשיכים עם מה שיש.
• מטמון: קובצי נתונים ליום, index.json ו-version.json לשעה, windows.ics ל-6 שעות, נקודת הקצה היומית ליום. מחרוזת שאילתה לא עוקפת את המטמון; משתמשים ב-version.json. לא לבדוק שום דבר יותר מפעם בשעה, ולשלוח User-Agent עם שם האפליקציה.
• גרסאות: שינויים ב-/v1/ הם הוספות בלבד; שינוי שובר ייצא כ-/v2/ עם 90 יום לפחות של חפיפה. data_version הוא גיבוב של הנתונים, ולכן משתנה רק כשערך משתנה (בכל ינואר, ואחרי תיקון). משווים אותו לשוויון בלבד.

8. תנאי שימוש

• חינם לכל שימוש, כולל מסחרי. בלי מפתח ובלי הרשמה.
• נשמח לקרדיט: היכן שמוצגים הזמנים, נא להציג "זמנים: zmanim.cc" עם קישור ל-https://zmanim.cc.
• בלי אחריות. הנתונים מסופקים כמות שהם. אנחנו משקיעים כדי שיהיו נכונים ומתקנים כל מה שמתגלה, אבל אין התחייבות שהם נקיים משגיאות או שהשירות יהיה זמין תמיד.
• אין כאן פסק הלכה. הזמנים הולכים לפי השיטות שמתוארות בעמוד הזה ולפי המנהגים המקומיים שנרשמו לכל עיר. בכל שאלה הלכתית יש להתייעץ עם הרב.
• מכשירים חייבים להיכשל בבטחה. מי שמפעיל משהו לפי הנתונים האלה צריך לחזור למצב המנוחה בכל פעם שהשעון, הרשת או הנתונים חסרים או לא ודאיים, ולאפשר לעקוף זאת ידנית.

יצירת קשר: באגים, שאלות או עיר להוספה: admin@zmanim.cc. נא לצרף את הכתובת שנקראה.