/v1/panchang/monthly

Month panchang — one row per day (tithi, nakshatra, yoga, vara, sunrise, sunset). Add include=sheet for a complete printable Hindu calendar page: tithi/nakshatra/moon-sign end-times in "27:07+" notation, kshaya days, moonrise/moonset, Hindu month, Vikram/Shaka samvat, moon phase and every festival of each day. Validated against 14 printed panchang calendars.

What this tells you

Monthly Panchang returns one row per calendar day — tithi, nakshatra (with pada), yoga, vara, and sunrise/sunset — for every day of the requested month. With `include=sheet` it becomes a complete printable Hindu calendar: per day the tithi/nakshatra/moon-sign end-times in the "27:07+" notation printed panchangs use, kshaya days with two tithis, moonrise/moonset, Hindu month (amanta and purnimanta), Vikram/Shaka samvat, ritu, ayana, moon phase and the full festival list of that day, plus the page header. One call per month is enough to render a printed-panchang-style calendar; the output was checked cell by cell against the printed panchang calendars of 14 cities (festival dates 100 %, end-times exact to the printed minute in 92 % of cells and ±1 min otherwise).

Parameters: `year`, `month`, `lat`, `lon` are required; `tz`, `alt`, `locale`, `include`, `month_system` and `ayanamsa` are optional; `date` and `time` are not used. `days[]` stays in English; `locale` applies only to `sheet[]`. With an IANA tz, `days[]` uses the UTC offset in force on the 15th of the month for every day, while `sheet[]` follows daylight-saving changes day by day. In `sheet[]`, sunrise/sunset are rounded to the nearest minute and end-times are truncated, as printed panchangs do. Printed panchangs use their own ephemeris, which differs from Swiss Ephemeris by a few seconds, so about 1 in 12 printed minutes can differ by one.

Request

All requests require an Authorization header with your dv_live_* API key.

example request

curl "https://api.lifeastroapi.com/v1/panchang/monthly?year=2027&month=1&lat=28.6139&lon=77.209&tz=Asia%2FKolkata" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query parameters

Checked against the API: a parameter is marked required when the request fails without it.

Name	Required	Example	Description
`year`	yes	`2027`	Year (YYYY).
`month`	yes	`1`	Month number (1–12).
`lat`	yes	`28.6139`	Latitude in decimal degrees.
`lon`	yes	`77.209`	Longitude in decimal degrees.
`tz`	no	`Asia/Kolkata`	Timezone: IANA name (Asia/Kolkata) or UTC offset (+05:30).
`include`	no	—	`sheet` (or `festivals`) adds the calendar sheet fields.
`locale`	no	—	Language for the `name` field: en (default), hi, mr, ta, kn, bn, gu, pa. `name_en` and `name_hi` are always present.
`month_system`	no	—	Lunar month convention for labels ("<Month> Amavasya"), the hindu_month field and month-membership vrats such as Shravan Somwar: purnimanta (default; North India) or amanta (South, West and East India). Festival dates never change with this option.
`ayanamsa`	no	—	Ayanamsa (sidereal offset) to use. Defaults to lahiri.

Response (200 OK)

The real response to the example request above, generated from the API itself. Long arrays are trimmed to their first two items. Field names are stable across versions.

200 response

{
  "year": 2027,
  "month": 1,
  "location": {
    "lat": 28.6139,
    "lon": 77.209,
    "alt": 0
  },
  "tz": "Asia/Kolkata",
  "days": [
    {
      "date": "2027-01-01",
      "day": 1,
      "vara_index": 5,
      "vara": "Friday",
      "tithi_index": 23,
      "tithi_name": "Navami",
      "tithi_paksha": "Krishna",
      "nakshatra_index": 13,
      "nakshatra_name": "Chitra",
      "nakshatra_pada": 3,
      "yoga_index": 5,
      "yoga_name": "Atiganda",
      "sunrise_jd": 2461406.571921,
      "sunset_jd": 2461407.003842,
      "sunrise_local": "2027-01-01 07:13:34",
      "sunset_local": "2027-01-01 17:35:32",
      "has_sunrise": true
    },
    {
      "date": "2027-01-02",
      "day": 2,
      "vara_index": 6,
      "vara": "Saturday",
      "tithi_index": 24,
      "tithi_name": "Dashami",
      "tithi_paksha": "Krishna",
      "nakshatra_index": 14,
      "nakshatra_name": "Swati",
      "nakshatra_pada": 3,
      "yoga_index": 6,
      "yoga_name": "Sukarma",
      "sunrise_jd": 2461407.572098,
      "sunset_jd": 2461408.004325,
      "sunrise_local": "2027-01-02 07:13:49",
      "sunset_local": "2027-01-02 17:36:14",
      "has_sunrise": true
    }
  ]
}

Field reference

Every field in the response, with its type, a real example, and what it means.

Field	Type	Meaning
year / month	integer	Echo of the requested Gregorian year (1800–2200) and month (1–12). example: `2027 / 1`
location	object	Echo of lat, lon and alt (metres). example: `{ "lat": 28.6139, "lon": 77.209, "alt": 0 }`
tz	string	Echo of the tz you sent; "UTC" when tz is not sent. Accepts IANA names, fixed offsets (+05:30) or decimal hours (5.5). example: `"Asia/Kolkata"`
days	array (28–31 items)	One entry per day of the month, with the elements at local sunrise. Always present. example: `[…]`
days[].date / days[].day	string / integer	The civil date and the day of the month. example: `"2027-01-01" / 1`
days[].vara_index / days[].vara	integer (0–6) / string	Weekday at sunrise. 0 = Sunday … 6 = Saturday. Name in English. example: `5 / "Friday"`
days[].tithi_index	integer (0–29)	Tithi at sunrise: 0 = Shukla Pratipada … 14 = Purnima, 15 = Krishna Pratipada … 29 = Amavasya. example: `23`
days[].tithi_name / days[].tithi_paksha	string	Tithi name and paksha (Shukla or Krishna), in English. example: `"Navami" / "Krishna"`
days[].nakshatra_index / nakshatra_name / nakshatra_pada	integer (0–26) / string / integer (1–4)	Moon's nakshatra and pada at sunrise. 0 = Ashwini … 26 = Revati. English names; the Purva/Uttara nakshatras use short forms such as "P.Phalguni". example: `13 / "Chitra" / 3`
days[].yoga_index / days[].yoga_name	integer (0–26) / string	Yoga at sunrise, in English. example: `5 / "Atiganda"`
days[].sunrise_jd / sunset_jd	number	Sunrise and sunset as Julian Day in UT. Left out when has_sunrise is false. example: `2461406.571921`
days[].sunrise_local / sunset_local	string (YYYY-MM-DD HH:MM:SS)	Local sunrise and sunset. Left out when has_sunrise is false. example: `"2027-01-01 07:13:34"`
days[].has_sunrise	boolean	false on polar days with no sunrise. The element fields of that day are then 0 or empty and must be ignored. example: `true`

Usage tips

How to use it

What include=sheet adds
Pass `include=sheet` (same cost; `include=festivals` does the same) to add three top-level fields: `header` (e.g. "Pausha - Magha 2083", the Hindu months the Gregorian month spans plus the Vikram samvat), `month_system` ("purnimanta" by default, or "amanta") and `sheet[]`, one object per day. Each `sheet[]` day has `date`, `day`, `vara`, `vara_en`, `vara_index`, `sunrise`, `sunset`, `moonrise`, `moonset` (local "HH:MM"), `tithi`, `nakshatra`, `moon_sign` (the one at sunrise) and `tithis`, `nakshatras`, `moon_signs` (every one current until the next sunrise), `yoga`, `yoga_en`, `hindu_month`, `hindu_month_amanta`, `hindu_month_purnimanta`, `is_adhik_maas` (only when true), `vikram_samvat`, `shaka_samvat`, `ritu`, `ayana`, `moon_phase` (new, waxing, full or waning) and `festivals[]` (the same objects as /v1/festivals/month).
Reading sheet end times
Each tithi, nakshatra and moon_sign object has `index`, `name`, `name_en`, `paksha` (tithi only), `end_local` ("YYYY-MM-DD HH:MM"), `end_display` and `end_jd`. `end_display` uses printed-panchang notation: "27:07+" means 03:07 on the next day. In `sheet[]` the indexes count from 1 (tithi 1–30, nakshatra 1–27, moon sign 1–12), unlike `days[]`, which counts from 0.
Build a printable calendar page
Request `include=sheet&locale=hi&alt=227` for Delhi. Render `header` as the title, each `sheet[]` entry as a cell: day number, `sunrise`/`sunset`, `tithi.name`, `moon_sign.name` + `end_display`, `nakshatra.name` + `end_display`, then `festivals[].name`.
South-Indian calendars
Pass `month_system=amanta` so `hindu_month` and the Amavasya/Purnima labels follow the amanta convention used in Maharashtra, Gujarat, Karnataka, Tamil Nadu, Andhra and Kerala. Festival dates never change with this option.
Kshaya and vriddhi days
When `tithis` has two entries, print both numbers ("26,27"); when the same tithi appears on two consecutive days it is a vriddhi day. Vrat dates in `festivals[]` already follow the classical udaya/pradosh/nishita/moonrise rules, so you do not need to resolve these yourself.
Cache per month and location
The sheet for a city and month never changes. Cache it for a year.

Errors

Every error follows the same envelope. Use the error.code field (not the message) for conditional logic in your integration.

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

402 Payment Required

{
  "error": {
    "code": "trial_exhausted",
    "message": "your free trial credits are exhausted — pick a plan to continue",
    "top_up_url": "https://lifeastroapi.com/pricing",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded; retry after 12 seconds",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

Try it

Get a dv_live_* key from your dashboard and paste into the cURL snippet above. New accounts get 1,500 free credits. Sign up.