/v1/panchang/tithi

Lunar day (tithi) at moment with transition times.

What this tells you

Tithi is one of the five limbs (panchang = "five limbs") of the Hindu almanac. It measures the angular distance between the Moon and the Sun — every 12° of separation = one tithi. There are 30 tithis in a lunar month, split into a waxing half (Shukla paksha) and waning half (Krishna paksha). Tithis drive every ritual timing in Hinduism: fasting days, festivals, pitru karma, and muhurta selection.

Request

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

example request

curl "https://api.divyastroapi.com/v1/panchang/tithi?date=2026-04-19&time=06%3A30&tz=%2B05%3A30" \
  -H "Authorization: Bearer dv_live_0123456789abcdef0123456789abcdef"

Query parameters

Name	Type	Required	Description
`date`	string	yes	ISO 8601 date
`time`	string	yes	24h HH:MM
`tz`	string	yes	IANA offset

Response (200 OK)

Successful requests return a JSON body. Field names are stable across versions.

200 response

{
  "tithi": {
    "index": 2,
    "name": "Dwitiya",
    "paksha": "Shukla"
  },
  "start_jd": 2461137.478,
  "end_jd":   2461138.362,
  "duration_hours": 21.2,
  "percent_complete": 34.6,
  "is_valid_at_sunrise": true,
  "ends_at": "2026-04-20T14:51:26+05:30"
}

Field reference

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

Field	Type	Meaning
tithi.index	integer (1–30)	Tithi number within the month. example: `2` Jyotish: Shukla paksha tithis are 1–15 (Pratipada → Purnima). Krishna paksha tithis are 16–30 (Pratipada → Amavasya).
tithi.name	string	Sanskrit name of the tithi. example: `"Dwitiya"` Jyotish: The 30 canonical names: Pratipada, Dwitiya, Tritiya, Chaturthi, Panchami, Shashti, Saptami, Ashtami, Navami, Dashami, Ekadashi, Dwadashi, Trayodashi, Chaturdashi, Purnima/Amavasya.
tithi.paksha	string	Lunar fortnight — waxing (Shukla) or waning (Krishna). example: `"Shukla" or "Krishna"`
start_jd	number	Julian Day when this tithi began. UT, not local time. example: `2461137.478`
end_jd	number	Julian Day when this tithi ends. example: `2461138.362`
duration_hours	number	Total duration of the tithi in hours. Tithis vary from ~19–26 hours. example: `21.2`
percent_complete	number (0–100)	How far through the tithi the requested moment falls. example: `34.6`
is_valid_at_sunrise	boolean	Whether this tithi was running at local sunrise. Traditional Indian calendars label a day by the tithi active at sunrise. example: `true`
ends_at	string (ISO 8601)	Local-time representation of end_jd for easy UI display. example: `"2026-04-20T14:51:26+05:30"`

Usage tips

How to use it

Cache per location per day
The tithi running at a given location only changes 1–2 times per day. Cache the response keyed by (date, lat, lon) for 6 hours.
Watch the sunrise rule
Indian traditional calendars label "today's tithi" as whatever was running at local sunrise. Use `is_valid_at_sunrise` and `/v1/panchang/sunrise-sunset` together to label dates correctly.
Handle tithi breaks
When one tithi ends mid-day and another begins, pass the second one to the next calendar cell. Never label a full day with a tithi that ends before noon.

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://divyastroapi.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 500 free credits. Sign up.