Panchang & Time Element APIs

1. Panchang Element Calculation (Tithi, Vara, Nakshatra, Yoga, Karana, Timings)

1. Name

Panchang Element Calculation (Tithi, Vara, Nakshatra, Yoga, Karana, Timings)

2. Purpose

Calculates daily Hindu Panchang elements (Five limbs of time: Tithi, Vaara, Nakshatra, Yoga, Karana) and critical solar/lunar timings (Sunrise, Sunset, Rahu Kalam, Yamagandam, Gulika Kalam, Abhijit Muhurta, Choghadiya) for a specific date and geographical coordinate. Used by calendar and daily Panchang widgets.

3. Endpoint

POST /api/v1/panchang/{element}

4. Auth

Type: None / API Key Header Example: X-API-Key: sk_live_5f6f2e0a690a45fae957c026cbd820c83bb55461bfad3b94

5. Request Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`.
`X-API-Key`	No	API Key required for authenticated access.

6. Request Payload

{
  "name": "Santhosh Murthy R",
  "datetime": "2026-07-29T06:00",
  "timezone": "Asia/Kolkata",
  "latitude": 11.3410,
  "longitude": 77.7172
}

7. Request Params Table

Field	Type	Required	Description	Allowed Values	Validation	Example
`element`	string	Yes (Path)	Panchang element key in URL path	`tithi`, `vara`, `nakshatra`, `yoga`, `karana`, `sunrise`, `sunset`, `moonrise`, `moonset`, `rahu-kalam`, `yamagandam`, `gulika-kalam`, `abhijit-muhurta`, `choghadiya`	Path Segment	`"tithi"`
`name`	string	No	User/Subject name	String	Max 200 chars	`"Santhosh"`
`datetime`	string	Yes	Target date and local time	ISO string	`YYYY-MM-DDTHH:MM`	`"2026-07-29T06:00"`
`timezone`	string	No	IANA timezone	Valid IANA TZ	Default: `"UTC"`	`"Asia/Kolkata"`
`latitude`	float	Yes	Latitude	`-90.0` to `+90.0`	Float	`11.3410`
`longitude`	float	Yes	Longitude	`-180.0` to `+180.0`	Float	`77.7172`

8. Request Example

{
  "datetime": "2026-07-29T06:00",
  "timezone": "Asia/Kolkata",
  "latitude": 11.3410,
  "longitude": 77.7172
}

9. Success Response

Status: 200 OK

{
  "status": "success",
  "message": "Calculated tithi successfully",
  "data": {
    "tithi_number": 15,
    "paksha": "Shukla",
    "is_rikta": false
  }
}

10. Response Fields Table

Field	Type	Description	Nullable	Example
`status`	string	Response result	No	`"success"`
`message`	string	Human readable message	No	`"Calculated tithi successfully"`
`data.tithi_number`	integer	Tithi index (1 to 30)	Yes	`15`
`data.paksha`	string	Fortnight phase (`Shukla` or `Krishna`)	Yes	`"Shukla"`
`data.is_rikta`	boolean	True if Tithi is classified as Rikta (4, 9, 14)	Yes	`false`
`data.start_time`	string	Start timestamp for timing window elements	Yes	`"06:05"`
`data.end_time`	string	End timestamp for timing window elements	Yes	`"07:35"`

11. Status Codes Table

Code	Meaning	When Returned
`200`	OK	Panchang calculation successful.
`400`	Bad Request	Missing `datetime`, `latitude`, or `longitude`.
`500`	Internal Error	Ephemeris calculation exception.

12. Error Examples

{
  "status": "error",
  "message": "Missing datetime, latitude, or longitude in request body",
  "data": null
}

Explanation: The client omitted location or datetime parameters required for Panchang calculation.

13. Frontend Usage Notes

Call /api/v1/panchang/tithi to show current Tithi and Paksha.
Call /api/v1/panchang/rahu-kalam to render inauspicious timing warnings for the day.

14. Validation Rules

latitude must be between -90 and +90.
longitude must be between -180 and +180.

15. Business Rules

Tithi is derived from the 12° angular separation increment between Moon and Sun ($Moon - Sun$).
Rahu Kalam, Yamagandam, and Gulika Kalam are computed dynamically using local sunrise and sunset timings.

16. Security Notes

Standard public API endpoint.

17. Performance Notes

Fast (~20ms).

POST /api/v1/muhurta

19. Example Frontend Flow

User selects a date on Panchang Calendar.
App fires calls to /api/v1/panchang/tithi and /api/v1/panchang/rahu-kalam.
App displays daily Panchang card.

20. Complete Example

Request:

POST /api/v1/panchang/tithi HTTP/1.1
Host: api.rbos.in
Content-Type: application/json

{
  "datetime": "2026-07-29T06:00",
  "timezone": "Asia/Kolkata",
  "latitude": 11.3410,
  "longitude": 77.7172
}

Response:

{
  "status": "success",
  "message": "Calculated tithi successfully",
  "data": {
    "tithi_number": 15,
    "paksha": "Shukla",
    "is_rikta": false
  }
}

Explanation: Calculates Tithi #15 (Purnima / Full Moon) in Shukla Paksha for Erode location on July 29, 2026.