Calendar & astronomy API

Access

Ask the site administrator for a token. Administrators can create, limit and revoke tokens under Account → Admin dashboard → API keys. Send it in Authorization: Bearer YOUR_TOKEN; never put it in a URL.

Public website tokens require an approved exact Origin. A public token can be copied by visitors; origins constrain browser access, not server identity. Private tokens must stay on your server. Both have per-token scopes, expiration and rate limits. Never embed a private token in browser code.

Production base: https://api.jewishcosmology.com/v1. Same-site and local base: /api/public/v1. GET and JSON POST are supported. No login session is required for token-authenticated requests.

Endpoints

Concise or detailed results

All endpoints default to concise data. Add detail: true in JSON, or detail=1 / detail=true in a query, to include the additional calendar dates, day numbers, resolved instants, model/settings metadata and sources. Omit the flag or use false/0 for concise output. Existing integrations expecting the original expanded response should add detail=true.

/convert with Gregorian or Julian input returns only hebrew and dow inside data. Hebrew input returns gregorian, julian and dow. The weekday belongs to the resolved Hebrew day (0 = Sunday, 6 = Shabbos), including after the evening boundary.

Hebrew date formatting

Optional on every endpoint, in both concise and detailed responses. Numeric date fields remain unchanged. A Hebrew date gains a sibling formatted_hebrew object with text, weekday, language, and direction. Historical as_of and reference dates gain as_of_formatted and reference_formatted. Conversion always includes top-level formatted_hebrew when formatting is requested, including Hebrew input.

Examples for 1 Tishri 5787 (12 September 2026), using /convert with the usual calendar/year/month/day input:

{"date_format":"dd/mm/yyyy, dow1"} → 01/01/5787, S
{"date_format":"d mmm yyyy"} → 1 Tish. 5787
{"date_format":"d/mmmm/yyyy, dowl","date_tradition":"sephardi"} → 1/Tishri/5787, Shabbat
{"date_format":"d mmmm yyyy","hebrew":true} → א׳ תשרי ה׳תשפ״ז
{"date_format":"dd/mm/yyyy, dows","hebrew":true,"day_format":"number","year_format":"number"} → 01/01/5787, שבת

Query example: /convert?calendar=gregorian&year=2026&month=9&day=12&date_format=d%20mmmm%20yyyy&hebrew=1. Without formatting options, response shapes remain unchanged.

Hebrew year

Call /year?year=5787. Only a Hebrew year from 1 to 10,000 is accepted; omit calendar or use hebrew. Do not send month, day or time. The token must include the new year permission, selectable when creating a key in the admin dashboard; existing keys retain their assigned permissions.

The response includes dechiyos (applied postponements; an empty array means none), year_type (deficient/regular/complete), keviah, length_days, leap, months, Rosh Hashanah and Pesach start dates, and Cheshvan/Kislev lengths. Holiday dates are the named Hebrew daylight dates, beginning the preceding evening; these fields do not imply a calculated sunset.

cycles.nineteen_year and cycles.twenty_eight_year each contain the cycle number and the year’s position within it, counted from year 1. tekufas_shmuel_nissan gives the traditional planetary-hour ruler and its symbol, not an observed planet’s zodiacal position.

elapsed_since.as_of identifies the date used for elapsed counts. Supply a selected Hebrew day with as_of: {"month": 2, "day": 16} (within the requested year), or query /year?year=5787&as_of[month]=2&as_of[day]=16. Without a selected date, the current Hebrew year uses today at the requested observer/timezone (default Jerusalem, with the usual day_boundary rules); other years use 1 Tishri. Calendar Year in Review follows the selected monthly-view day, with the same today/1-Tishri fallback. All six historical counters use this date. At Adam epoch 0, elapsed reference counts gain one when converted to Hebrew year labels. Reference dates are 9 Av 3831 for the Beis Hamikdash · Bayis Sheini, 9 Av 3339 for the Beis Hamikdash · Bayis Rishon, and 15 Nisan 2449 for Yetzias Mitzrayim. Override the Exodus year with exodus_year (1–10,000), for example /year?year=5787&exodus_year=2449&detail=1.

Beis Hamikdash · Bayis Rishon milestones are included under elapsed_since.first_temple_foundation (2 Iyyar 2929), first_temple_completion (8 Cheshvan 2929), and first_temple_inauguration (23 Tishri 2938). These baseline years shift by exodus_year − 2449; the destruction dates use the same Adam epoch. The foundation year is 480 years after the Exodus year; completion and inauguration use offsets of 480 and 489 years respectively. In the app, the same reference year is saved under Settings → Epoch → Historical dates; API clients pass it explicitly with exodus_year.

historical_labels supplies display names alongside the unchanged historical keys. Use temple_names=beis-hamikdash (default) or temple_names=holy-temple, with date_tradition=ashkenaz|sephardi|temani for Bayis / Bayit / Bayith. hebrew=1 returns Hebrew labels. In the app, choose the wording under Settings → Display → Names and pronunciation under General → Transliteration.

The completion day is configurable in the same app settings, defaulting to 8 Cheshvan. API clients override it with temple_completion_day, for example /year?year=5787&exodus_year=2449&temple_completion_day=12. The day must exist in Cheshvan of the shifted completion year (29 or 30 days). This is a configurable counting date. Month-end anniversaries clamp to the last day when the anniversary month is shorter.

Each reference returns signed total_days, complete total_months and days_after_total_months, plus elapsed: {years, months, days}. The latter counts complete Hebrew anniversaries, then calendar months, then remaining days. Month counts and components are nonnegative magnitudes; direction is before/after the reference date. Leap months are counted as actual months, not averages. Detailed output also includes civil dates, Tishri’s mean molad and calculation definitions.

Dates & location

Required for daily endpoints: calendar (gregorian, julian or hebrew), integer year, month, day. Hebrew months start at Tishri = 1 and run sequentially; leap years include Adar I = 6 and Adar II = 7. Civil calendars are proleptic, with astronomical year numbering (0 = 1 BCE). Supported dates lie within Hebrew years 1–10,000.

No time means the daylight date before 18:00. Optional time uses HH:mm:ss. Timed conversion defaults to the calculated sunset; set day_boundary: "18:00" for a fixed cutoff. Hebrew evening inputs resolve to the preceding civil date. Polar dates without a sunset require an explicit fixed cutoff.

Default location: Jerusalem Temple Mount, latitude 31.778, longitude 35.2354, timezone Asia/Jerusalem. Supply both latitude and longitude to change location, and timezone for its civil clock. An IANA timezone applies historical DST automatically. To use standard/fixed time, send offset_minutes (east positive) and dst: false. Do not combine a fixed offset with automatic DST. Ambiguous DST times use occurrence: "earlier" or "later"; nonexistent times are rejected.

elevation_enabled defaults to false. If true, elevation is metres above sea level (default 740 m). No terrain or buildings are inferred. diaspora defaults to false (Israel). Optional purim: unwalled (default), walled or doubtful. Boolean query parameters use 0/1; JSON accepts true/false.

Readings

tradition may be all, ashkenaz, sephardi, temani, gra, chabad, mizrachi, italian, moroccan, arizal or chassidish. Temani currently means Baladi; Gra retains its Israel custom. Festival and special maftir precedence come from the same tables as the calendar. Sources accompany detailed responses.

Mizrachi, Italian, Moroccan, Arizal and Chassidish are reserved but currently return status: "source_required" with empty readings until a specific verified community table is supplied. No other rite is silently substituted.

Zmanim settings

Use zman: ["neitz", "shema", "shkiya"] to select times; omit it for all. Defaults: alos120, alos90, alos72, neitz, shema, tefillah, chatzos, minchaGedolah, seven, nine, minchaKetanah, shkiya, tzeis, eveningShema. These use the app’s configurable rules, not a claim of rabbinic approval.

Optional settings: dayStart (neitz, alos72, alos90, alos120), dayEnd (shkiya), milMinutes (default 18), milUnits (seasonal or equal). Supply settings.zmanim to replace the rules with objects containing id, label, amount, anchor (neitz/shkiya/alos72/alos90/alos120), units (equal minutes, seasonal minutes or mil). Defaults follow the application. Missing sunrise/sunset yields explicit null times.

settings.solar supports angle (degrees), limb (upper/center/lower), refraction (boolean), refractionMethod (fixed34/bennett), pressure (hPa), temperature (°C). Solar profiles apply to zmanim and timed conversion. The /sun and /moon endpoints use astronomical upper-limb horizons and accept the refraction flag. All astronomy uses VSOP2000 and EP2MM-C.

Molad & time output

/molad requires Hebrew year and month, without a day. basis: mean, true or both (default). The mean molad belongs to the named month, even when it occurs before Rosh Chodesh; its reference is fixed Jerusalem standard UTC+02:00, counted from 18:00. True molad is the nearest geocentric ecliptic-longitude conjunction.

display_clock: jerusalem-standard (default) or local. time_format: hours-chalakim-regaim (default), minutes-chalakim, or civil. There are 1080 chalakim/hour and 76 regaim/chelek. Concise event timestamps include ISO UTC, Hebrew date, the requested time format, timezone and 18:00 day boundary. Detailed timestamps additionally include UTC Julian date, Gregorian/Julian dates and civil clock time. Display changes never shift the physical instant; the Hebrew event label uses the stated 18:00 display-day boundary.

kiddush_start: 3 or 7 days; kiddush_end: half or 15. These are age limits from the mean molad. They do not impose darkness, weather or Moon visibility; use the Moon endpoint for local horizon events.

Example

curl -X POST https://api.jewishcosmology.com/v1/convert \
  -H 'Authorization: Bearer YOUR_PRIVATE_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"calendar":"gregorian","year":2026,"month":9,"day":12}'

{"api_version":"1","data":{"hebrew":{"year":5787,"month":1,"day":1},"dow":{"number":6,"name":"Shabbos"}}}

Success wraps results in api_version and data. Errors return message and validation errors where applicable: 401 invalid token, 403 origin/scope denied, 422 invalid input, 429 rate limit, 503 calculator unavailable. Honor Retry-After and use bounded retries.