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

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 the response.

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. Event timestamps include UTC Julian date, ISO UTC, Hebrew date and Gregorian/Julian dates. 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":{"dates":{"hebrew":{"year":5787,"month":1,"day":1},"gregorian":{"year":2026,"month":9,"day":12},"julian":{"year":2026,"month":8,"day":30}}}}

Example response abbreviated. 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.