{ "openapi": "3.0.3", "info": { "title": "Hebcal REST APIs", "version": "1.0.0", "description": "Hebcal.com publishes a family of free, public Jewish calendar / Hebrew date / zmanim REST APIs. All endpoints support HTTP and HTTPS (HTTP/2), gzip and brotli compression, and HTTP Keep-Alive.\n\nContent generated by these APIs is licensed under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/).\n\nReference documentation:\n- [Jewish Calendar API](https://www.hebcal.com/home/195/jewish-calendar-rest-api)\n- [Hebrew Date Converter API](https://www.hebcal.com/home/219/hebrew-date-converter-rest-api)\n- [Zmanim API](https://www.hebcal.com/home/1663/zmanim-halachic-times-api)\n- [Leyning (Torah Reading) API](https://www.hebcal.com/home/4277/leyning-torah-reading-api)\n- [Yahrzeit + Anniversary API](https://www.hebcal.com/home/1705/yahrzeit-anniversary-api)\n- [Assur Melacha (Work Forbidden) API](https://www.hebcal.com/home/4984/assur-melacha-work-forbidden-api)\n- [Specifying a location for Jewish calendar APIs](https://www.hebcal.com/home/4912/specifying-a-location-for-jewish-calendar-apis)\n- [Event language support](https://www.hebcal.com/home/4534/jewish-calendar-event-language-support)", "contact": { "name": "Hebcal", "url": "https://www.hebcal.com/home/about" }, "license": { "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/" } }, "servers": [ { "url": "https://www.hebcal.com", "description": "Production" } ], "tags": [ {"name": "Jewish Calendar", "description": "Jewish holidays, Parashat ha-Shavua, candle lighting times, daily learning, Hebrew dates and more.", "externalDocs": {"url": "https://www.hebcal.com/home/195/jewish-calendar-rest-api"}}, {"name": "Hebrew Date Converter", "description": "Convert between Gregorian and Hebrew dates (single date or range).", "externalDocs": {"url": "https://www.hebcal.com/home/219/hebrew-date-converter-rest-api"}}, {"name": "Zmanim", "description": "Halachic (sun-based) times for any city or coordinates.", "externalDocs": {"url": "https://www.hebcal.com/home/1663/zmanim-halachic-times-api"}}, {"name": "Leyning", "description": "Torah Reading details: full kriyah aliyot, haftarah, and triennial cycle.", "externalDocs": {"url": "https://www.hebcal.com/home/4277/leyning-torah-reading-api"}}, {"name": "Yahrzeit", "description": "Personal calendar of yahrzeit (memorial) dates, Hebrew birthdays, and Hebrew anniversaries.", "externalDocs": {"url": "https://www.hebcal.com/home/1705/yahrzeit-anniversary-api"}}, {"name": "Assur Melacha", "description": "Determine whether a given moment falls within a melacha (work-forbidden) period such as Shabbat or a Yom Tov.", "externalDocs": {"url": "https://www.hebcal.com/home/4984/assur-melacha-work-forbidden-api"}} ], "paths": { "/hebcal": { "get": { "tags": ["Jewish Calendar"], "summary": "Jewish Calendar", "description": "Returns Jewish holidays, candle lighting times, Parashat ha-Shavua, daily learning schedules and more.\n\nDate range may be specified by `year` (with optional `month`, `ny`, `yt`) **or** by both `start` and `end`.", "operationId": "getJewishCalendar", "parameters": [ {"name": "v", "in": "query", "required": true, "schema": {"type": "string", "enum": ["1"], "default": "1"}, "description": "API version. Must be `1`."}, {"name": "cfg", "in": "query", "required": true, "schema": {"type": "string", "enum": ["json", "fc", "rss", "ics", "csv"], "default": "json"}, "description": "Output format: `json` (default REST), `fc` (FullCalendar.io JSON), `rss`, `ics` (iCalendar), or `csv`."}, {"name": "year", "in": "query", "example": "now", "schema": {"oneOf": [{"type": "integer"}, {"type": "string", "enum": ["now"]}]}, "description": "Gregorian or Hebrew year (4-digit). Use `now` for the current year. Interpreted as Gregorian unless `yt=H`."}, {"name": "yt", "in": "query", "schema": {"type": "string", "enum": ["G", "H"], "default": "G"}, "description": "Year type: `G` for Gregorian (default) or `H` for Hebrew."}, {"name": "month", "in": "query", "example": "x", "schema": {"oneOf": [{"type": "integer", "minimum": 1, "maximum": 12}, {"type": "string", "enum": ["x"]}]}, "description": "Single Gregorian month 1–12, or `x` for entire year (default)."}, {"name": "ny", "in": "query", "schema": {"type": "integer", "minimum": 1, "default": 1}, "description": "Number of years to render (default 1). Only honored together with `year`."}, {"name": "start", "in": "query", "schema": {"type": "string", "format": "date"}, "description": "Gregorian start date (YYYY-MM-DD). Use with `end` instead of `year`."}, {"name": "end", "in": "query", "schema": {"type": "string", "format": "date"}, "description": "Gregorian end date (YYYY-MM-DD)."}, {"name": "maj", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "example": "on", "description": "Major holidays (Rosh Hashana, Yom Kippur, Pesach, etc.)."}, {"name": "min", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Minor holidays (Tu BiShvat, Lag B'Omer, etc.)."}, {"name": "mod", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Modern holidays (Yom HaAtzmaut, Yom HaShoah, etc.)."}, {"name": "nx", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Rosh Chodesh."}, {"name": "mf", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Minor fasts."}, {"name": "ss", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Special Shabbatot."}, {"name": "yto", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Yom Tov only. Suppresses all other event options."}, {"name": "s", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Parashat ha-Shavuah on Saturday."}, {"name": "leyning", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Include full Torah reading details (default `on` when `s=on`)."}, {"name": "D", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Show Hebrew date for dates that have an event."}, {"name": "d", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Show Hebrew date for entire date range."}, {"name": "o", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Days of the Omer."}, {"name": "ykk", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Yom Kippur Katan."}, {"name": "molad", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Molad — moment of new moon for each month."}, {"name": "yzkr", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Yizkor dates."}, {"name": "mvch", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Shabbat Mevarchim."}, {"name": "i", "in": "query", "schema": {"type": "string", "enum": ["on", "off"], "default": "off"}, "description": "Diaspora (`off`, default) or Israel (`on`) holiday/Torah schedule."}, {"name": "c", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Include candle lighting times. Requires a location (see location parameters below)."}, {"name": "b", "in": "query", "schema": {"type": "integer", "default": 18}, "description": "Minutes before sunset for candle lighting. Defaults: 18 (most cities), 40 (Jerusalem), 30 (Haifa, Zikhron Ya'akov)."}, {"name": "M", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Calculate Havdalah at nightfall (tzeit hakochavim)."}, {"name": "m", "in": "query", "schema": {"type": "integer", "default": 0}, "description": "Fixed minutes after sundown for Havdalah. `0` disables Havdalah."}, {"name": "fsd", "in": "query", "schema": {"type": "number", "exclusiveMinimum": true, "minimum": 0, "exclusiveMaximum": true, "maximum": 90, "default": 16.1}, "description": "Minor fasts begin when the sun is this many degrees below the horizon in the morning (default 16.1°, Alot HaShachar). Takes precedence over `fsm`. Tish'a B'Av always begins at sunset. Requires `c=on` and a location."}, {"name": "fsm", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 240}, "description": "Minor fasts begin this many minutes before sunrise (e.g. 72 or 90). Honors `ue`. Ignored when `fsd` is given."}, {"name": "fed", "in": "query", "schema": {"type": "number", "exclusiveMinimum": true, "minimum": 0, "exclusiveMaximum": true, "maximum": 90, "default": 7.083}, "description": "Minor fasts end when the sun is this many degrees below the horizon in the evening. Default is 7.083° in the Diaspora, or 15 minutes after sunset in Israel. Takes precedence over `fem`. Does not affect Tish'a B'Av."}, {"name": "fem", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 240}, "description": "Minor fasts end this many minutes after sunset. Honors `ue`. Ignored when `fed` is given. Does not affect Tish'a B'Av."}, {"name": "tbed", "in": "query", "schema": {"type": "number", "exclusiveMinimum": true, "minimum": 0, "exclusiveMaximum": true, "maximum": 90, "default": 6.45}, "description": "Tish'a B'Av ends when the sun is this many degrees below the horizon in the evening (default 6.45°, Rabbi Yechiel Michel Tucazinsky). Takes precedence over `tbem`."}, {"name": "tbem", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 240}, "description": "Tish'a B'Av ends this many minutes after sunset. Honors `ue`. Ignored when `tbed` is given."}, {"$ref": "#/components/parameters/Geonameid"}, {"$ref": "#/components/parameters/Zip"}, {"$ref": "#/components/parameters/City"}, {"$ref": "#/components/parameters/Latitude"}, {"$ref": "#/components/parameters/Longitude"}, {"$ref": "#/components/parameters/Tzid"}, {"$ref": "#/components/parameters/Elev"}, {"$ref": "#/components/parameters/Ue"}, {"name": "F", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Daf Yomi"}, {"name": "dw", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Daf-a-Week"}, {"name": "yyomi", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Yerushalmi Yomi (Vilna)"}, {"name": "yys", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Yerushalmi Yomi (Schottenstein)"}, {"name": "myomi", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Mishna Yomi"}, {"name": "nyomi", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Nach Yomi"}, {"name": "dty", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Tanakh Yomi"}, {"name": "dps", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Daily Tehillim (Psalms)"}, {"name": "dr1", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Daily Rambam (1 chapter/day)"}, {"name": "dr3", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Daily Rambam (3 chapters/day)"}, {"name": "dsm", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Maimonides' Sefer HaMitzvot"}, {"name": "dksa", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Kitzur Shulchan Arukh Yomi"}, {"name": "ahsy", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Arukh HaShulchan Yomi"}, {"name": "dcc", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Sefer Chofetz Chaim"}, {"name": "dshl", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Shemirat HaLashon"}, {"name": "dpa", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "Pirkei Avot (on Shabbatot between Pesach and Rosh Hashanah)"}, {"$ref": "#/components/parameters/Lg"}, {"name": "hdp", "in": "query", "schema": {"type": "string", "enum": ["1"]}, "description": "Include `heDateParts` field on untimed items."}, {"name": "callback", "in": "query", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_.]+$"}, "description": "JSONP callback function name (alphanumeric, periods, underscores)."} ], "responses": { "200": { "description": "Calendar feed. For `cfg=json` the body is an object containing the requested date `range`, the resolved `location` (when candle lighting is enabled), and an `items` array of calendar events — holidays, Torah portions, candle-lighting/Havdalah times, Rosh Chodesh, Omer count, daily-learning entries and Hebrew dates. For `cfg=ics`/`csv`/`rss`/`fc` the body is iCalendar text, CSV text, RSS XML, or FullCalendar JSON respectively.", "content": { "application/json": {"schema": {"$ref": "#/components/schemas/HebcalResponse"}, "examples": { "may2015LosAngeles": {"summary": "Major holidays for May 2015 in Los Angeles", "externalValue": "https://www.hebcal.com/hebcal?v=1&cfg=json&maj=on&year=2015&month=5&geonameid=3448439"}, "dafYomi": {"summary": "Daf Yomi for one day", "externalValue": "https://www.hebcal.com/hebcal?cfg=json&v=1&F=on&start=2022-06-07&end=2022-06-07"} }}, "text/calendar": {"schema": {"type": "string"}}, "text/csv": {"schema": {"type": "string"}}, "application/rss+xml": {"schema": {"type": "string"}} } }, "400": {"$ref": "#/components/responses/HebcalBadRequest"}, "404": {"$ref": "#/components/responses/NotFound"} } } }, "/converter": { "get": { "tags": ["Hebrew Date Converter"], "summary": "Convert between Gregorian and Hebrew dates", "description": "Four modes are supported:\n\n1. **Gregorian → Hebrew (single date):** pass `g2h=1` with `date=YYYY-MM-DD` (or `gy`/`gm`/`gd`).\n2. **Gregorian → Hebrew (range):** pass `g2h=1` with `start` and `end` (max 180 days; `cfg=json` only).\n3. **Hebrew → Gregorian (single date):** pass `h2g=1` with `hy`, `hm`, `hd`.\n4. **Hebrew → Gregorian (range):** pass `h2g=1` with `hy`, `hm`, `hd`, `ndays` (2–180; `cfg=json` only).\n\nMonth name (`hm`) accepts: `Nisan`, `Iyyar`/`Iyar`, `Sivan`, `Tamuz`/`Tammuz`, `Av`, `Elul`, `Tishrei`, `Cheshvan`, `Kislev`, `Tevet`/`Teves`, `Sh'vat`/`Shvat`, `Adar`/`Adar1`/`Adar I`/`Adar2`/`Adar II`. Hebrew UTF-8 names are also accepted. In a leap year `Adar` is `Adar2`; in a non-leap year all three Adars are equivalent.", "operationId": "convertHebrewDate", "parameters": [ {"name": "cfg", "in": "query", "required": true, "schema": {"type": "string", "enum": ["json", "xml"], "default": "json"}, "description": "Output format. Range queries require `json`."}, {"name": "g2h", "in": "query", "schema": {"type": "string", "enum": ["1"], "default": "1"}, "description": "Set to `1` for Gregorian→Hebrew conversion. Mutually exclusive with `h2g`."}, {"name": "h2g", "in": "query", "schema": {"type": "string", "enum": ["1"]}, "description": "Set to `1` for Hebrew→Gregorian conversion. Mutually exclusive with `g2h`."}, {"name": "date", "in": "query", "schema": {"type": "string", "format": "date"}, "description": "Gregorian date (YYYY-MM-DD). Used in single-date g2h mode as an alternative to `gy`/`gm`/`gd`."}, {"name": "gy", "in": "query", "schema": {"type": "integer", "example": 2026}, "description": "Gregorian year (g2h)."}, {"name": "gm", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 12, "example": 6}, "description": "Gregorian month 1–12 (g2h). Leading zero optional."}, {"name": "gd", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 31, "example": 17}, "description": "Gregorian day 1–31 (g2h). Leading zero optional."}, {"name": "gs", "in": "query", "schema": {"$ref": "#/components/schemas/OnOff"}, "description": "After-sunset designation. When `on`, returns the Hebrew date of the next day (sunset starts the new Hebrew day)."}, {"name": "hy", "in": "query", "schema": {"type": "integer", "example": 5786}, "description": "Hebrew year (h2g)."}, {"name": "hm", "in": "query", "schema": {"type": "string", "example": "Kislev"}, "description": "Hebrew month name (h2g)."}, {"name": "hd", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 30, "example": 25}, "description": "Hebrew day 1–30 (h2g)."}, {"name": "ndays", "in": "query", "schema": {"type": "integer", "minimum": 2, "maximum": 180}, "description": "Number of days to convert in h2g range mode (2–180)."}, {"name": "start", "in": "query", "schema": {"type": "string", "format": "date"}, "description": "Range start date YYYY-MM-DD (g2h range mode)."}, {"name": "end", "in": "query", "schema": {"type": "string", "format": "date"}, "description": "Range end date YYYY-MM-DD (g2h range mode). Truncated to 180 days from `start`."}, {"name": "i", "in": "query", "schema": {"type": "string", "enum": ["on", "off"]}, "description": "When `on`, use Israel holiday schedule when listing events for a date."}, {"name": "strict", "in": "query", "schema": {"type": "string", "enum": ["1"]}, "description": "Return HTTP 400 for invalid input dates instead of redirecting to a fallback."}, {"$ref": "#/components/parameters/Lg"}, {"name": "callback", "in": "query", "schema": {"type": "string", "pattern": "^[A-Za-z0-9_.]+$"}, "description": "JSONP callback name."} ], "responses": { "200": { "description": "Converted date(s). Single-date queries return a `ConverterSingleResponse` with the Gregorian fields (`gy`/`gm`/`gd`), the equivalent Hebrew date (`hy`/`hm`/`hd`), a formatted `hebrew` string, and any holiday/parsha `events` falling on that Hebrew date. Range queries (`start`/`end` or `h2g` + `ndays`) return a `ConverterRangeResponse` whose `hdates` object maps each Gregorian date to its conversion.", "content": { "application/json": { "schema": {"oneOf": [{"$ref": "#/components/schemas/ConverterSingleResponse"}, {"$ref": "#/components/schemas/ConverterRangeResponse"}]}, "examples": { "g2hSingle": {"summary": "Gregorian → Hebrew (single)", "externalValue": "https://www.hebcal.com/converter?cfg=json&date=2011-06-02&g2h=1&strict=1"}, "g2hRange": {"summary": "Gregorian → Hebrew (range)", "externalValue": "https://www.hebcal.com/converter?cfg=json&start=2021-12-29&end=2022-01-04&g2h=1"}, "h2gSingle": {"summary": "Hebrew → Gregorian (single)", "externalValue": "https://www.hebcal.com/converter?cfg=json&hy=5749&hm=Kislev&hd=25&h2g=1&strict=1"}, "h2gRange": {"summary": "Hebrew → Gregorian (range)", "externalValue": "https://www.hebcal.com/converter?cfg=json&hy=5749&hm=Kislev&hd=25&h2g=1&ndays=90&strict=1"} } }, "text/xml": {"schema": {"type": "string"}} } }, "400": {"$ref": "#/components/responses/ConverterBadRequest"} } } }, "/zmanim": { "get": { "tags": ["Zmanim", "Assur Melacha"], "summary": "Halachic times for a date or range; or check whether a moment is assur bemelacha", "description": "Two modes:\n\n1. **Zmanim mode (default):** Returns sun-based halachic times for a single `date` or a `start`/`end` range.\n2. **Assur Melacha mode:** Pass `im=1` and (optionally) `dt=` to determine whether that moment falls within a melacha (work-forbidden) period such as Shabbat or a Yom Tov. The check uses solar depression of 8.5°.\n\nA location is required (see location parameters).", "operationId": "getZmanim", "parameters": [ {"name": "cfg", "in": "query", "required": true, "schema": {"type": "string", "enum": ["json"], "default": "json"}, "description": "Output format. Must be `json`."}, {"name": "date", "in": "query", "schema": {"type": "string", "format": "date"}, "description": "Single Gregorian date YYYY-MM-DD. If neither `date` nor `start/end` are specified, defaults to today at the location."}, {"name": "start", "in": "query", "schema": {"type": "string", "format": "date"}, "description": "Range start date YYYY-MM-DD."}, {"name": "end", "in": "query", "schema": {"type": "string", "format": "date"}, "description": "Range end date YYYY-MM-DD. Capped at 180 days from `start`."}, {"name": "sec", "in": "query", "schema": {"type": "integer", "enum": [0, 1], "default": 0}, "description": "If `1`, output time-of-day with seconds precision (otherwise rounded to the nearest minute)."}, {"name": "im", "in": "query", "schema": {"type": "string", "enum": ["1", "on"]}, "description": "Assur Melacha mode. When set, returns `status.isAssurBemlacha` instead of zmanim."}, {"name": "dt", "in": "query", "schema": {"type": "string", "format": "date-time"}, "description": "Used with `im=1`. Specific moment to check, in ISO 8601 format `YYYY-MM-DDTHH:mm:ss.sssZ`. Timezone offset can be `Z` or `±HH:MM`. URL-encode `+` as `%2b`. If omitted, uses the current time at the location."}, {"$ref": "#/components/parameters/Geonameid"}, {"$ref": "#/components/parameters/Zip"}, {"$ref": "#/components/parameters/City"}, {"$ref": "#/components/parameters/Latitude"}, {"$ref": "#/components/parameters/Longitude"}, {"$ref": "#/components/parameters/Tzid"}, {"$ref": "#/components/parameters/Elev"}, {"$ref": "#/components/parameters/Ue"} ], "responses": { "200": { "description": "In zmanim mode, a `ZmanimResponse` containing the resolved `location` and a `times` object of ISO 8601 halachic times (dawn, sunrise, sof zman Shema/Tfilla, chatzot, mincha, plag, sunset, the various tzeit/nightfall opinions, etc.); for a range, each time becomes an object keyed by date. In Assur Melacha mode (`im=1`), an `AssurMelachaResponse` whose `status.isAssurBemlacha` boolean indicates whether the moment falls within a work-forbidden (Shabbat/Yom Tov) period.", "content": { "application/json": { "schema": {"oneOf": [{"$ref": "#/components/schemas/ZmanimResponse"}, {"$ref": "#/components/schemas/AssurMelachaResponse"}]}, "examples": { "singleDate": {"summary": "Zmanim for one date", "externalValue": "https://www.hebcal.com/zmanim?cfg=json&geonameid=3448439&date=2021-03-23"}, "range": {"summary": "Zmanim for a range", "externalValue": "https://www.hebcal.com/zmanim?cfg=json&geonameid=3448439&start=2021-01-15&end=2021-01-22"}, "assurMelacha": {"summary": "Assur Melacha status", "externalValue": "https://www.hebcal.com/zmanim?cfg=json&geonameid=3448439&im=1&dt=2025-06-21T20:08:10Z"} } } } }, "400": {"$ref": "#/components/responses/ZmanimBadRequest"}, "404": {"$ref": "#/components/responses/NotFound"} } } }, "/leyning": { "get": { "tags": ["Leyning"], "summary": "Torah readings for a date or range", "description": "Returns full kriyah aliyot, haftarah, and (optionally) triennial cycle readings. Use either a single `date` or both `start` and `end` (capped at 180 days).", "operationId": "getLeyning", "parameters": [ {"name": "cfg", "in": "query", "required": true, "schema": {"type": "string", "enum": ["json"], "default": "json"}, "description": "Output format. Must be `json`."}, {"name": "date", "in": "query", "schema": {"type": "string", "format": "date", "example": "2026-06-20"}, "description": "Single Gregorian date YYYY-MM-DD. Equivalent to `start=date&end=date`."}, {"name": "start", "in": "query", "schema": {"type": "string", "format": "date"}, "description": "Range start date YYYY-MM-DD."}, {"name": "end", "in": "query", "schema": {"type": "string", "format": "date"}, "description": "Range end date YYYY-MM-DD. Capped at 180 days from `start`."}, {"name": "i", "in": "query", "schema": {"type": "string", "enum": ["on", "off"], "default": "off"}, "description": "Diaspora (`off`, default) or Israel (`on`) Torah reading schedule."}, {"name": "triennial", "in": "query", "schema": {"type": "string", "enum": ["on", "off"], "default": "on"}, "description": "Include triennial cycle aliyot. Defaults to `on`. (Triennial only available for Hebrew year 5745 and later.)"} ], "responses": { "200": { "description": "A `LeyningResponse` containing the requested `range` and an `items` array, one entry per Torah-reading occasion (Shabbat parsha, holiday reading, Rosh Chodesh, weekday Monday/Thursday reading, etc.). Each item gives the reading `name` (English/Hebrew), a `summary` verse range, the `fullkriyah` aliyot (keyed `1`–`7` plus `M` for maftir, each with book and beginning/ending verse), the `haftarah` (text plus structured `haft`), any `weekday` reading, and — when `triennial=on` — the `triennial` aliyot with the corresponding `triYear` and `triHaftara`.", "content": { "application/json": {"schema": {"$ref": "#/components/schemas/LeyningResponse"}, "examples": { "singleDate": {"summary": "Single Shabbat (Parashat Korach)", "externalValue": "https://www.hebcal.com/leyning?cfg=json&date=2026-06-20"}, "rangeExample": {"summary": "Sukkot week 5783", "externalValue": "https://www.hebcal.com/leyning?cfg=json&start=2022-09-21&end=2022-09-26"} }} } }, "400": {"$ref": "#/components/responses/LeyningBadRequest"} } } }, "/yahrzeit": { "post": { "tags": ["Yahrzeit"], "summary": "Yahrzeit, Hebrew birthday and Hebrew anniversary calendar", "description": "Calculates the Hebrew anniversary of an event (death, birth, marriage, etc.) for a number of years.\n\n**HTTPS is required.** The body must be `application/x-www-form-urlencoded`.\n\nProvide one or more event records using a numeric suffix `1`, `2`, `3`… for each person/event. For each record, supply either Gregorian date fields (`yX`, `mX`, `dX`, optional `sX`) **or** Hebrew date fields (`hyX`, `hmX`, `hdX`).\n\nExample (curl):\n```\ncurl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \\\\\n --data-raw 'cfg=json&v=yahrzeit&n1=Person1&t1=Birthday&d1=15&m1=4&y1=1983&s1=on&years=3' \\\\\n https://www.hebcal.com/yahrzeit\n```", "operationId": "getYahrzeit", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": {"$ref": "#/components/schemas/YahrzeitRequest"}, "encoding": {"hmX": {"contentType": "text/plain; charset=utf-8"}} } } }, "responses": { "200": { "description": "A `YahrzeitResponse` containing the computed `range` of Hebrew years and an `items` array. Each item is one observance — the Hebrew anniversary (yahrzeit/birthday/anniversary) or a Yizkor date — with its Gregorian `date`, Hebrew date (`hdate`), `category`, the source record `name`, and which `anniversary` (1st, 2nd, …) it represents.", "content": { "application/json": {"schema": {"$ref": "#/components/schemas/YahrzeitResponse"}} } }, "400": {"$ref": "#/components/responses/YahrzeitBadRequest"} } } } }, "components": { "parameters": { "Geonameid": { "name": "geonameid", "in": "query", "schema": {"type": "integer", "example": 5128581}, "description": "GeoNames.org numeric city identifier. The Hebcal database supports approximately 150,000 world cities with population ≥ 1,000 (refreshed annually from the [`cities1000.zip`](https://download.geonames.org/export/dump/) feed).\n\n**Examples:**\n- `3448439` — São Paulo, BR\n- `5128581` — New York, US\n- `5368361` — Los Angeles, US\n- `281184` — Jerusalem, IL" }, "Zip": { "name": "zip", "in": "query", "schema": {"type": "string", "pattern": "^\\d{5}"}, "description": "5-digit US ZIP code (e.g. `90210`). ZIP+4 input is truncated to the first 5 digits." }, "City": { "name": "city", "in": "query", "schema": {"type": "string"}, "description": "**Deprecated.** Legacy Hebcal city identifier (e.g. `GB-London`). Case-insensitive. Prefer `geonameid`.", "deprecated": true }, "Latitude": { "name": "latitude", "in": "query", "schema": {"type": "number", "format": "double", "minimum": -90, "maximum": 90}, "description": "Decimal latitude (-90.0 to 90.0). Must be combined with `longitude` and `tzid`." }, "Longitude": { "name": "longitude", "in": "query", "schema": {"type": "number", "format": "double", "minimum": -180, "maximum": 180}, "description": "Decimal longitude (-180.0 to 180.0). Must be combined with `latitude` and `tzid`." }, "Tzid": { "name": "tzid", "in": "query", "schema": {"type": "string"}, "description": "TZ database identifier such as `America/New_York` or `Asia/Jerusalem`. Required when using `latitude`/`longitude`." }, "Elev": { "name": "elev", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 9000}, "description": "Elevation in meters (1–9000). Only honored when `ue=on`." }, "Ue": { "name": "ue", "in": "query", "schema": {"type": "string", "enum": ["on", "off"], "default": "off"}, "description": "Use elevation in sunrise/sunset calculations." }, "Lg": { "name": "lg", "in": "query", "schema": {"type": "string", "enum": [ "s", "a", "h", "he", "he-x-NoNikud", "sh", "ah", "ashkenazi_standard", "ashkenazi_litvish", "ashkenazi_poylish", "ashkenazi_romanian", "de", "es", "fi", "fr", "hu", "nl", "pl", "pt", "ro", "ru", "uk" ], "default": "s"}, "description": "Event-title locale. Default `s` (Sephardic transliteration).\n\n| Code | Language |\n|------|----------|\n| `s` | Sephardic transliterations (default) |\n| `a` | Ashkenazic transliterations |\n| `h` / `he` | Hebrew |\n| `he-x-NoNikud` | Hebrew without diacritics |\n| `sh` | Sephardic transliteration with Hebrew |\n| `ah` | Ashkenazic transliteration with Hebrew |\n| `ashkenazi_standard` | Ashkenazic transliteration (standard) |\n| `ashkenazi_litvish` | Ashkenazic transliteration (Litvish) |\n| `ashkenazi_poylish` | Ashkenazic transliteration (Poylish) |\n| `ashkenazi_romanian` | Ashkenazic transliteration (Romanian variant) |\n| `de` | German |\n| `es` | Spanish |\n| `fi` | Finnish |\n| `fr` | French |\n| `hu` | Hungarian |\n| `nl` | Dutch |\n| `pl` | Polish |\n| `pt` | Portuguese |\n| `ro` | Romanian |\n| `ru` | Russian |\n| `uk` | Ukrainian |" } }, "schemas": { "OnOff": { "type": "string", "enum": ["on", "off", "1", "0"], "description": "Boolean flag. Use `on` or `1` to enable, `off` or `0` to disable." }, "Location": { "type": "object", "properties": { "title": {"type": "string"}, "city": {"type": "string"}, "tzid": {"type": "string", "description": "IANA timezone identifier."}, "latitude": {"type": "number"}, "longitude": {"type": "number"}, "cc": {"type": "string", "description": "ISO 3166 country code."}, "country": {"type": "string"}, "admin1": {"type": "string"}, "asciiname": {"type": "string"}, "geo": {"type": "string", "enum": ["geoname", "zip", "pos", "none"]}, "geonameid": {"type": "integer"}, "elevation": {"type": "integer"} } }, "HebcalResponse": { "type": "object", "properties": { "title": {"type": "string"}, "date": {"type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the response was generated."}, "location": {"$ref": "#/components/schemas/Location"}, "range": { "type": "object", "properties": { "start": {"type": "string", "format": "date"}, "end": {"type": "string", "format": "date"} } }, "items": {"type": "array", "items": {"$ref": "#/components/schemas/HebcalItem"}} } }, "HebcalItem": { "type": "object", "properties": { "title": {"type": "string", "description": "Event title in selected locale."}, "date": {"type": "string", "description": "Either `YYYY-MM-DD` (untimed) or full ISO 8601 with timezone (timed events like candle lighting)."}, "hdate": {"type": "string", "description": "Hebrew date string (when requested)."}, "category": {"type": "string", "enum": ["candles", "havdalah", "holiday", "parashat", "dafyomi", "mishnayomi", "nachyomi", "yerushalmi", "roshchodesh", "omer", "molad", "mevarchim", "hebdate", "user", "fast"]}, "subcat": {"type": "string"}, "hebrew": {"type": "string"}, "memo": {"type": "string"}, "link": {"type": "string", "format": "uri"}, "leyning": {"type": "object", "additionalProperties": true, "description": "Torah-reading detail for this event (parsha summary, aliyot, haftarah) when `leyning=on`. See the Leyning API for the full shape."}, "yomtov": {"type": "boolean"}, "heDateParts": {"$ref": "#/components/schemas/HeDateParts"} } }, "HeDateParts": { "type": "object", "properties": { "y": {"type": "string", "description": "Hebrew year in gematriya."}, "m": {"type": "string", "description": "Hebrew month name."}, "d": {"type": "string", "description": "Hebrew day in gematriya."} } }, "ConverterSingleResponse": { "type": "object", "properties": { "gy": {"type": "integer"}, "gm": {"type": "integer", "minimum": 1, "maximum": 12}, "gd": {"type": "integer", "minimum": 1, "maximum": 31}, "afterSunset": {"type": "boolean"}, "hy": {"type": "integer"}, "hm": {"type": "string"}, "hd": {"type": "integer", "minimum": 1, "maximum": 30}, "hebrew": {"type": "string", "description": "Hebrew date with diacritics."}, "heDateParts": {"$ref": "#/components/schemas/HeDateParts"}, "events": {"type": "array", "items": {"type": "string"}, "description": "Holiday/parsha names that fall on this Hebrew date."}, "il": {"type": "boolean"} } }, "ConverterRangeResponse": { "type": "object", "properties": { "start": {"type": "string", "format": "date"}, "end": {"type": "string", "format": "date"}, "locale": {"type": "string"}, "hdates": { "type": "object", "additionalProperties": {"$ref": "#/components/schemas/ConverterSingleResponse"}, "description": "Object mapping each Gregorian date (YYYY-MM-DD) to its Hebrew conversion." } } }, "ZmanimResponse": { "type": "object", "properties": { "date": {"oneOf": [{"type": "string", "format": "date"}, {"type": "object", "properties": {"start": {"type": "string", "format": "date"}, "end": {"type": "string", "format": "date"}}}]}, "version": {"type": "string"}, "location": {"$ref": "#/components/schemas/Location"}, "times": {"$ref": "#/components/schemas/ZmanimTimes"} } }, "ZmanimTimes": { "type": "object", "description": "ISO 8601 timestamps with timezone offset. For range queries, each property is an object mapping `YYYY-MM-DD` → time. Times calculated using NOAA solar algorithms (expect 1-2 minute variation from other sources).", "properties": { "chatzotNight": {"type": "string", "description": "Chatzot HaLailah — sunset plus 6 halachic hours."}, "alotHaShachar": {"type": "string", "description": "Alot haShachar — sun is 16.1° below horizon in the morning."}, "alosBaalHatanya": {"type": "string", "description": "Alot HaShachar (Baal Hatanya) — sun 16.9° below horizon in the morning."}, "misheyakir": {"type": "string", "description": "Earliest talis & tefillin (sun 11.5° below horizon)."}, "misheyakirMachmir": {"type": "string", "description": "Earliest talis & tefillin (sun 10.2° below horizon)."}, "dawn": {"type": "string", "description": "Civil dawn — sun is 6° below horizon."}, "sunrise": {"type": "string", "description": "Sunrise (upper edge of sun, 0.833° above horizon)."}, "seaLevelSunrise": {"type": "string", "description": "Sunrise at sea level (only when `ue=on`)."}, "sofZmanShma": {"type": "string", "description": "Latest Shema (Gra)."}, "sofZmanShmaMGA": {"type": "string", "description": "Latest Shema (MGA, 72 min)."}, "sofZmanShmaMGA16Point1": {"type": "string", "description": "Latest Shema (MGA, 16.1°)."}, "sofZmanShmaMGA19Point8": {"type": "string", "description": "Latest Shema (MGA, 19.8°)."}, "sofZmanShmaBaalHatanya": {"type": "string", "description": "Latest Shema (Baal Hatanya)."}, "sofZmanTfilla": {"type": "string", "description": "Latest Shacharit (Gra)."}, "sofZmanTfillaMGA": {"type": "string", "description": "Latest Shacharit (MGA, 72 min)."}, "sofZmanTfillaMGA16Point1": {"type": "string", "description": "Latest Shacharit (MGA, 16.1°)."}, "sofZmanTfillaMGA19Point8": {"type": "string", "description": "Latest Shacharit (MGA, 19.8°)."}, "sofZmanTfilaBaalHatanya": {"type": "string", "description": "Latest Shacharit (Baal Hatanya)."}, "chatzot": {"type": "string", "description": "Midday — sunrise plus 6 halachic hours."}, "minchaGedola": {"type": "string", "description": "Earliest Mincha (Gra)."}, "minchaGedolaMGA": {"type": "string", "description": "Earliest Mincha (MGA)."}, "minchaGedolaBaalHatanya": {"type": "string", "description": "Earliest Mincha (Baal Hatanya)."}, "minchaKetana": {"type": "string", "description": "Preferable earliest Mincha (Gra)."}, "minchaKetanaMGA": {"type": "string", "description": "Preferable earliest Mincha (MGA)."}, "minchaKetanaBaalHatanya": {"type": "string", "description": "Preferable earliest Mincha (Baal Hatanya)."}, "plagHaMincha": {"type": "string", "description": "Plag HaMincha — sunrise plus 10.75 halachic hours."}, "plagHaminchaBaalHatanya": {"type": "string", "description": "Plag HaMincha (Baal Hatanya)."}, "sunset": {"type": "string", "description": "Sunset (upper edge of sun, 0.833° below horizon)."}, "seaLevelSunset": {"type": "string", "description": "Sunset at sea level (only when `ue=on`)."}, "beinHaShmashos": {"type": "string", "description": "Twilight — 13.5 minutes prior to tzeit (sun 7.083° below)."}, "dusk": {"type": "string", "description": "Civil dusk — sun is 6° below horizon."}, "tzeit7083deg": {"type": "string", "description": "Nightfall — sun 7.083° below horizon."}, "tzeit85deg": {"type": "string", "description": "Nightfall — sun 8.5° below horizon."}, "tzeit42min": {"type": "string", "description": "Nightfall — fixed 42 minutes after sunset."}, "tzeit50min": {"type": "string", "description": "Nightfall — fixed 50 minutes after sunset."}, "tzeit72min": {"type": "string", "description": "Nightfall — fixed 72 minutes after sunset (Rabbeinu Tam)."}, "tzaisBaalHatanya": {"type": "string", "description": "Nightfall (Baal Hatanya) — sun 6° below western geometric horizon after sunset."} } }, "AssurMelachaResponse": { "type": "object", "properties": { "date": {"type": "string", "format": "date-time", "description": "ISO 8601 response timestamp."}, "version": {"type": "string"}, "location": {"$ref": "#/components/schemas/Location"}, "status": { "type": "object", "properties": { "localTime": {"type": "string", "format": "date-time", "description": "ISO 8601 with timezone offset."}, "isAssurBemlacha": {"type": "boolean", "description": "True if the moment is within a melacha (work-forbidden) period."} } } } }, "LeyningResponse": { "type": "object", "properties": { "date": {"type": "string", "format": "date-time"}, "location": {"type": "string", "enum": ["Diaspora", "Israel"]}, "range": { "type": "object", "properties": { "start": {"type": "string", "format": "date"}, "end": {"type": "string", "format": "date"} } }, "items": {"type": "array", "items": {"$ref": "#/components/schemas/LeyningItem"}} } }, "LeyningItem": { "type": "object", "properties": { "date": {"type": "string", "format": "date"}, "hdate": {"type": "string", "description": "Hebrew date."}, "name": { "type": "object", "properties": {"en": {"type": "string"}, "he": {"type": "string"}} }, "summary": {"type": "string", "description": "Verse range summary, e.g. `Genesis 1:1-6:8`."}, "fullkriyah": {"type": "object", "additionalProperties": {"$ref": "#/components/schemas/Aliyah"}, "description": "Full kriyah aliyot keyed by aliyah number (`1`–`7`) and `M` for Maftir."}, "haft": {"type": "array", "items": {"$ref": "#/components/schemas/Aliyah"}, "description": "Structured haftarah reading (one or more verse ranges)."}, "haftara": {"type": "string", "description": "Haftarah reference as plain text, e.g. `Isaiah 66:1 - 66:24`."}, "weekday": {"type": "object", "additionalProperties": {"$ref": "#/components/schemas/Aliyah"}, "description": "Weekday Torah reading aliyot (Mondays/Thursdays), keyed `1`–`3`."}, "triennial": {"type": "object", "additionalProperties": {"$ref": "#/components/schemas/Aliyah"}, "description": "Triennial cycle aliyot (when `triennial` is on and Hebrew year ≥ 5745), keyed `1`–`7` and `M`."}, "triYear": {"type": "integer", "minimum": 1, "maximum": 3, "description": "Year (1, 2, or 3) within the triennial cycle."}, "triHaftara": {"type": "string", "description": "Triennial haftarah reference as plain text."}, "triHaft": {"type": "array", "items": {"$ref": "#/components/schemas/Aliyah"}, "description": "Structured triennial haftarah reading."} } }, "Aliyah": { "type": "object", "description": "A single Torah (or haftarah) reading segment.", "properties": { "k": {"type": "string", "description": "Book of the Bible, e.g. `Numbers`."}, "b": {"type": "string", "description": "Beginning chapter:verse, e.g. `16:1`."}, "e": {"type": "string", "description": "Ending chapter:verse, e.g. `18:32`."}, "v": {"type": "integer", "description": "Number of verses in this segment."}, "p": {"type": "integer", "minimum": 1, "maximum": 54, "description": "Parsha number (1–54) for the regular annual reading, when applicable."}, "reason": {"type": "string", "description": "Explanation when this reading differs from the regular schedule (e.g. a special Shabbat or holiday)."} } }, "YahrzeitRequest": { "type": "object", "required": ["cfg", "v"], "properties": { "cfg": {"type": "string", "enum": ["json"]}, "v": {"type": "string", "enum": ["yahrzeit"]}, "years": {"type": "integer", "default": 20, "example": 20, "description": "Number of Hebrew years to compute (default 20). Use `years=1` for a single year."}, "start": {"type": "integer", "example": 5786, "description": "Starting Hebrew year (defaults to the current Hebrew year, e.g. 5786)."}, "end": {"type": "integer", "description": "Ending Hebrew year (inclusive). Defaults to `start + years`."}, "hebdate": {"type": "string", "enum": ["on", "off"], "default": "off", "description": "Append Hebrew date to event titles."}, "yizkor": {"type": "string", "enum": ["on", "off"], "default": "off", "description": "Include Yizkor dates."}, "i": {"type": "string", "enum": ["on", "off"], "description": "Yizkor schedule: `off` for Diaspora, `on` for Israel."}, "hdp": {"type": "integer", "enum": [0, 1], "description": "If `1`, include `heDateParts` field on all-day items."}, "y1": {"type": "integer", "example": 1948, "description": "Gregorian year for record #1 (4-digit)."}, "m1": {"type": "integer", "minimum": 1, "maximum": 12, "example": 4, "description": "Gregorian month 1–12 for record #1."}, "d1": {"type": "integer", "minimum": 1, "maximum": 31, "example": 15, "description": "Gregorian day-of-month for record #1."}, "s1": {"type": "string", "enum": ["on", "off"], "example": "on", "description": "Whether record #1 occurred after sunset."}, "t1": {"type": "string", "enum": ["Yahrzeit", "Birthday", "Anniversary", "Other"], "example": "Yahrzeit", "description": "Type of anniversary for record #1 (case-sensitive)."}, "n1": {"type": "string", "example": "Sarah Cohen", "description": "Person/event name for record #1."}, "hy1": {"type": "integer", "description": "Hebrew year for record #1 (alternative to Gregorian)."}, "hm1": {"type": "string", "description": "Hebrew month for record #1 (Hebrew UTF-8 or transliterated)."}, "hd1": {"type": "integer", "minimum": 1, "maximum": 30, "description": "Hebrew day-of-month for record #1."} }, "additionalProperties": { "description": "For multiple records, repeat the per-record fields with incrementing suffixes (e.g. `y2`, `m2`, `d2`, `t2`, `n2`, `s2`, or `hy2`, `hm2`, `hd2`) for record #2, and so on." }, "example": { "cfg": "json", "v": "yahrzeit", "n1": "Sarah Cohen", "t1": "Yahrzeit", "d1": 15, "m1": 4, "y1": 1948, "s1": "on", "years": 20 } }, "YahrzeitResponse": { "type": "object", "properties": { "title": {"type": "string"}, "date": {"type": "string", "format": "date-time"}, "version": {"type": "string"}, "range": { "type": "object", "properties": { "start": {"type": "string", "format": "date"}, "end": {"type": "string", "format": "date"} } }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": {"type": "string"}, "date": {"type": "string", "format": "date"}, "hdate": {"type": "string"}, "memo": {"type": "string"}, "name": {"type": "string"}, "category": {"type": "string", "enum": ["yahrzeit", "birthday", "anniversary", "yizkor", "other"]}, "anniversary": {"type": "integer", "description": "Which anniversary this represents (1, 2, 3, …)."}, "heDateParts": {"$ref": "#/components/schemas/HeDateParts"} } } } } }, "Error": { "type": "object", "properties": { "error": {"type": "string", "description": "Human-readable error message."} } } }, "responses": { "BadRequest": { "description": "Invalid input. The body is an `Error` object whose `error` property describes the problem.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}} }, "HebcalBadRequest": { "description": "Invalid input. Common causes:\n- A required parameter is missing — e.g. `Please specify required parameter 'v'`.\n- A required parameter was supplied more than once — e.g. `Invalid duplicate parameter 'year'`.\n- `year` exceeds the supported maximum — `Gregorian year cannot be greater than 9999: 12000` or `Hebrew year cannot be greater than 13760: 14000`.\n- The selected options produce no events for the requested range — `No events`.\n- A malformed location parameter (e.g. invalid `latitude`/`longitude`, or `latitude`/`longitude` supplied without `tzid`). See also `404` for unknown `geonameid`/`zip`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "examples": { "missingParam": {"summary": "Missing required parameter", "value": {"error": "Please specify required parameter 'v'"}}, "yearTooLarge": {"summary": "Year out of range", "value": {"error": "Gregorian year cannot be greater than 9999: 12000"}}, "noEvents": {"summary": "No events for the selected options", "value": {"error": "No events"}} }}} }, "ConverterBadRequest": { "description": "Invalid input. Common causes:\n- A range query (`start`/`end`, or `ndays`) was requested without `cfg=json` — `Date range conversion using 'start' and 'end' requires cfg=json`.\n- A required field for the chosen direction is missing — e.g. `Missing parameter 'hy' for conversion from Hebrew to Gregorian` or `Missing parameter 'gd' for conversion from Gregorian to Hebrew`.\n- `ndays` is not a valid number — `Invalid value for ndays: foo`.\n- A Gregorian date is malformed or out of range — `Date does not match format YYYY-MM-DD: 2026-13-01`, `Gregorian month out of valid range 1-12: 13`, `Gregorian day 30 out of valid range for 2/2026`, or `Gregorian year cannot be greater than 9999: 12000`.\n- An unrecognized Hebrew month name — e.g. `Unable to parse month name: Foobar`.\n- A Hebrew day outside the month's length — e.g. `Hebrew day out of valid range 1-29 for Kislev 5786`, or `Hebrew year must be year 1 or later: 0`.\n\nNote: `400` is only returned for invalid dates when `strict=1`; otherwise the API falls back to a nearby valid date.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "examples": { "badGregMonth": {"summary": "Gregorian month out of range", "value": {"error": "Gregorian month out of valid range 1-12: 13"}}, "badGregDay": {"summary": "Impossible Gregorian day (e.g. Feb 30)", "value": {"error": "Gregorian day 30 out of valid range for 2/2026"}}, "badHebMonth": {"summary": "Unknown Hebrew month name", "value": {"error": "Unable to parse month name: Foobar"}}, "badHebDay": {"summary": "Hebrew day out of range", "value": {"error": "Hebrew day out of valid range 1-29 for Kislev 5786"}}, "rangeNeedsJson": {"summary": "Range query without cfg=json", "value": {"error": "Date range conversion using 'start' and 'end' requires cfg=json"}} }}} }, "ZmanimBadRequest": { "description": "Invalid input. Common causes:\n- `cfg=json` is missing — `Parameter cfg=json is required`.\n- No location was supplied — `Location is required` (provide `geonameid`, `zip`, or `latitude`+`longitude`+`tzid`).\n- A malformed location — e.g. `Invalid latitude specified: 200`, `Invalid longitude specified: foo`, `Timezone required`, or `geo=pos requires latitude, longitude, tzid parameters`.\n- A malformed `date`/`start`/`end` — e.g. `Invalid Date: 2026-02-30`.\n- A malformed `dt` (Assur Melacha mode) ISO 8601 datetime.\n\nSee also `404` for an unknown `geonameid`/`zip`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "examples": { "missingCfg": {"summary": "Missing cfg=json", "value": {"error": "Parameter cfg=json is required"}}, "missingLocation": {"summary": "No location supplied", "value": {"error": "Location is required"}}, "badLatitude": {"summary": "Invalid latitude", "value": {"error": "Invalid latitude specified: 200"}}, "badDate": {"summary": "Invalid date", "value": {"error": "Invalid Date: 2026-02-30"}} }}} }, "LeyningBadRequest": { "description": "Invalid input. Common causes:\n- `cfg=json` is missing — `Parameter cfg=json is required`.\n- Neither `date` nor both `start` and `end` were supplied — e.g. `Parameter 'start' is required`.\n- A malformed date — `Date does not match format YYYY-MM-DD: 2026-13-01`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "examples": { "missingCfg": {"summary": "Missing cfg=json", "value": {"error": "Parameter cfg=json is required"}}, "missingStart": {"summary": "Missing date/start/end", "value": {"error": "Parameter 'start' is required"}}, "badDate": {"summary": "Malformed date", "value": {"error": "Date does not match format YYYY-MM-DD: 2026-13-01"}} }}} }, "YahrzeitBadRequest": { "description": "Invalid input. Common causes:\n- An unsupported output format was requested — `This API does not support cfg=fc` or `This API does not support cfg=xml` (only `cfg=json` is supported here).\n- A date field in one of the records is malformed or impossible — e.g. `Gregorian day 30 out of valid range for 2/1983`, `Gregorian month out of valid range 1-12: 13`, `Unable to parse month name: Foobar`, or `Hebrew day out of valid range 1-29 for Kislev 5749`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "examples": { "unsupportedCfg": {"summary": "Unsupported output format", "value": {"error": "This API does not support cfg=fc"}}, "badGregDay": {"summary": "Impossible Gregorian day", "value": {"error": "Gregorian day 30 out of valid range for 2/1983"}} }}} }, "NotFound": { "description": "Geographic identifier not found — e.g. `Sorry, can't find geonameid: 99999999` or `Sorry, can't find ZIP code: 00000`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "examples": { "geonameid": {"summary": "Unknown geonameid", "value": {"error": "Sorry, can't find geonameid: 99999999"}}, "zip": {"summary": "Unknown ZIP code", "value": {"error": "Sorry, can't find ZIP code: 00000"}} }}} } } } }