/v1/panchang/tithi

Lunar day (tithi) at moment with transition times.

What this tells you

Tithi is one of the five limbs of the panchang ("five limbs"). It measures the angle between the Moon and the Sun: every 12° of separation is one tithi, so a lunar month has 30 tithis. The first 15 form the waxing half (Shukla paksha) and the last 15 the waning half (Krishna paksha). Tithis set the dates of fasts, festivals and shraddha, and are a key input to muhurta selection. This endpoint returns the tithi running at local sunrise on `date`, which is how traditional calendars name the tithi of a day, together with the moment it ends.

`end_jd` is a Julian Day in UT. `end_local` is local wall-clock time in the request `tz`, formatted "YYYY-MM-DD HH:MM:SS" with no offset. If the Sun does not rise on `date` (polar day or night) the API returns 422 `data_unavailable`, because the tithi is anchored to sunrise.

Request

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

example request

curl "https://api.lifeastroapi.com/v1/panchang/tithi?date=2027-01-15&tz=Asia%2FKolkata&lat=28.6139&lon=77.209" \
  -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
`date`	yes	`2027-01-15`	Date (YYYY-MM-DD).
`tz`	yes	`Asia/Kolkata`	Timezone: IANA name (Asia/Kolkata) or UTC offset (+05:30).
`lat`	yes	`28.6139`	Latitude in decimal degrees.
`lon`	yes	`77.209`	Longitude in decimal degrees.

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

{
  "date": "2027-01-15",
  "location": {
    "lat": 28.6139,
    "lon": 77.209,
    "alt": 0
  },
  "tz": "Asia/Kolkata",
  "index": 6,
  "name": "Saptami",
  "paksha": "Shukla",
  "tithi_in_paksha": 7,
  "deity": "Surya",
  "type": "Bhadra",
  "end_jd": 2461420.863881,
  "end_local": "2027-01-15 14:13:59"
}

Field reference

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

Field	Type	Meaning
date	string	Echo of the `date` parameter (local date). example: `"2027-01-15"`
location	object	Echo of `lat`, `lon` and `alt` (metres, default 0). example: `{ "lat": 28.6139, "lon": 77.209, "alt": 0 }`
tz	string	Echo of the `tz` parameter. `end_local` is in this zone. example: `"Asia/Kolkata"`
index	integer (0–29)	Position of the tithi in the lunar month, counted from 0. 0–14 are Shukla paksha (Pratipada to Purnima), 15–29 are Krishna paksha (Pratipada to Amavasya). example: `6` Jyotish: Tithi = floor((Moon longitude − Sun longitude) / 12°). Every 12° of Moon–Sun separation is one tithi.
name	string	Name of the tithi. example: `"Saptami"` Jyotish: The 15 names repeat in each paksha: Pratipada, Dwitiya, Tritiya, Chaturthi, Panchami, Shashthi, Saptami, Ashtami, Navami, Dashami, Ekadashi, Dwadashi, Trayodashi, Chaturdashi, then Purnima (Shukla) or Amavasya (Krishna).
paksha	string	"Shukla" (waxing fortnight) or "Krishna" (waning fortnight). example: `"Shukla"`
tithi_in_paksha	integer (1–15)	Position of the tithi within its paksha. Purnima and Amavasya are both 15. example: `7`
deity	string	Presiding deity of the tithi. example: `"Surya"` Jyotish: Both pakshas share the same deity for the same tithi (Dashami = Yama), except the 15th: Purnima is Chandra, Amavasya is Pitru.
type	string	Tithi group: Nanda, Bhadra, Jaya, Rikta or Purna. example: `"Bhadra"` Jyotish: The five groups repeat in order every five tithis. Rikta tithis (Chaturthi, Navami, Chaturdashi) are traditionally avoided for new beginnings.
end_jd	number	When this tithi ends, as a Julian Day in UT. example: `2461420.863881`
end_local	string (YYYY-MM-DD HH:MM:SS)	When this tithi ends, in local time (request `tz`), with no offset suffix. Often falls on the next date. example: `"2027-01-15 14:13:59"`

Usage tips

How to use it

Sunrise tithi, not the current one
The tithi is always taken at sunrise on `date`. The `time` parameter does not change it. If you need the tithi at a later moment and `end_local` has already passed, the next tithi (index + 1, wrapping 29 → 0) is running.
Cache per date and location
The result depends only on `date`, `lat`, `lon`, `alt` and `tz`. Cache it for the whole day.
Kshaya tithis are not listed
Only the sunrise tithi and its end time are returned. If a short tithi starts and ends before the next sunrise (kshaya tithi), it does not appear here. Call again with the next `date` to get the following sunrise tithi.
Localized names
Pass `locale` (for example `hi`) to get `name`, `paksha`, `deity` and `type` in that language. Use `index` for logic, not the name.

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.