Electional Astrology (Muhurta) APIs

1. Auspicious Timing (Muhurta) Calculation

1. Name

Auspicious Timing (Muhurta) Calculation

2. Purpose

Calculates auspicious window timings (Shubh Muhurta) for major events such as Marriage, House Warming (Griha Pravesh), Business Launch, Travel, Vehicle Purchase, and Naming Ceremony. Used by event planning tools.

3. Endpoint

POST /api/v1/muhurta

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,
  "event_type": "marriage"
}

7. Request Params Table

Field	Type	Required	Description	Allowed Values	Validation	Example
`name`	string	No	User/Subject name	String	Max 200 chars	`"Santhosh"`
`datetime`	string	Yes	Target start date	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`
`event_type`	string	No	Activity category	`"marriage"`, `"house-warming"`, `"business"`, `"travel"`, `"naming-ceremony"`, `"vehicle-purchase"`	Enum	`"marriage"`

8. Request Example

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

9. Success Response

Status: 200 OK

{
  "status": "success",
  "message": "Muhurta calculated successfully",
  "data": {
    "event_type": "marriage",
    "is_auspicious": true,
    "quality_score": 85,
    "windows": [
      {
        "start_time": "09:15",
        "end_time": "11:45",
        "tithi": "Shukla Dwitiya",
        "nakshatra": "Rohini"
      }
    ]
  }
}

10. Response Fields Table

Field	Type	Description	Nullable	Example
`status`	string	Result status	No	`"success"`
`data.is_auspicious`	boolean	True if window meets electional criteria	No	`true`
`data.quality_score`	integer	Muhurta rating score (0 to 100)	No	`85`
`data.windows[].start_time`	string	Window start time	No	`"09:15"`
`data.windows[].end_time`	string	Window end time	No	`"11:45"`

11. Status Codes Table

Code	Meaning	When Returned
`200`	OK	Muhurta calculated successfully.
`400`	Bad Request	Missing input parameters.
`500`	Internal Error	Calculation error.

12. Error Examples

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

13. Frontend Usage Notes

Display green calendar highlights for auspicious Muhurta windows (is_auspicious: true).

14. Validation Rules

latitude and longitude required.

15. Business Rules

Avoids Rahu Kalam and Rikta Tithis for marriage and business events.

16. Security Notes

Standard public API endpoint.

17. Performance Notes

Fast (~35ms).

POST /api/v1/panchang/tithi

19. Example Frontend Flow

User chooses "Marriage" in Muhurta tool.
App calls /api/v1/muhurta.
App lists suitable time slots.

20. Complete Example

Request:

POST /api/v1/muhurta 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,
  "event_type": "marriage"
}

Response:

{
  "status": "success",
  "message": "Muhurta calculated successfully",
  "data": { "is_auspicious": true, "quality_score": 85 }
}

Explanation: Calculates marriage Muhurta window for specified date and location.