Dosha Analysis APIs

1. Dosha Check (Manglik, Kaal Sarp, Pitru, Guru Chandal, Kemadruma, Grahan)

1. Name

Dosha Check (Manglik, Kaal Sarp, Pitru, Guru Chandal, Kemadruma, Grahan)

2. Purpose

Audits the chart for major astrological afflictions/Doshas (Manglik / Kuja Dosha, Kaal Sarp Dosha, Pitru Dosha, Guru Chandal Yoga, Kemadruma Yoga, and Grahan Dosha) along with severity ratings and classical cancellation rules (Bhanga). Used by frontend for remedies and affliction reports.

3. Endpoint

POST /api/v1/doshas/{dosha_type} or POST /api/v1/doshas

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": "1983-10-01T20:50",
  "timezone": "Asia/Kolkata",
  "latitude": 11.3410,
  "longitude": 77.7172
}

7. Request Params Table

Field	Type	Required	Description	Allowed Values	Validation	Example
`dosha_type`	string	No (Path)	Specific Dosha key in URL path	`manglik`, `kaal-sarp`, `pitru-dosha`, `guru-chandal`, `kemadruma`, `grahan`	Path Segment	`"manglik"`
`name`	string	No	Native name	String	Max 200 chars	`"Santhosh"`
`datetime`	string	Yes	Birth local datetime	ISO string	`YYYY-MM-DDTHH:MM`	`"1983-10-01T20:50"`
`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

{
  "name": "Santhosh Murthy R",
  "datetime": "1983-10-01T20:50",
  "timezone": "Asia/Kolkata",
  "latitude": 11.3410,
  "longitude": 77.7172
}

9. Success Response

Status: 200 OK

{
  "status": "success",
  "message": "Calculated MANGLIK dosha successfully",
  "data": {
    "dosha": "MANGLIK",
    "is_present": true,
    "severity": "HIGH",
    "is_cancelled": false,
    "cancellation_reason": null,
    "remedies": [
      "Worship Lord Hanuman on Tuesdays",
      "Recite Hanuman Chalisa"
    ]
  }
}

10. Response Fields Table

Field	Type	Description	Nullable	Example
`status`	string	Result status	No	`"success"`
`message`	string	Human readable message	No	`"Calculated MANGLIK dosha successfully"`
`data.dosha`	string	Dosha key evaluated	No	`"MANGLIK"`
`data.is_present`	boolean	True if Dosha is active in chart	No	`true`
`data.severity`	string	Affliction intensity level (`LOW`, `MEDIUM`, `HIGH`)	Yes	`"HIGH"`
`data.is_cancelled`	boolean	True if classical cancellation rule (Bhanga) applies	No	`false`
`data.cancellation_reason`	string	Explanation of cancellation rule if cancelled	Yes	`null`
`data.remedies`	array	List of classical remedies	Yes	`["Worship Lord Hanuman..."]`

11. Status Codes Table

Code	Meaning	When Returned
`200`	OK	Dosha evaluation successful.
`400`	Bad Request	Missing birth parameters or invalid Dosha path.
`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

Show warning badges for is_present: true and green "Cancelled" badges when is_cancelled: true.

14. Validation Rules

Required parameters: datetime, latitude, longitude.

15. Business Rules

Manglik status checks Mars in houses 1, 4, 7, 8, 12 from Lagna, Moon, and Venus.

16. Security Notes

Standard public API endpoint.

17. Performance Notes

Fast (~30ms).

POST /api/v1/chart
POST /api/v1/match/manglik

19. Example Frontend Flow

User opens "Doshas & Remedies" screen.
UI calls /api/v1/doshas.
UI renders Dosha status cards and prescribed remedies.

20. Complete Example

Request:

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

{
  "name": "Santhosh",
  "datetime": "1983-10-01T20:50",
  "timezone": "Asia/Kolkata",
  "latitude": 11.3410,
  "longitude": 77.7172
}

Response:

{
  "status": "success",
  "message": "Calculated MANGLIK dosha successfully",
  "data": {
    "dosha": "MANGLIK",
    "is_present": true,
    "severity": "HIGH",
    "is_cancelled": false
  }
}

Explanation: Checks Manglik (Kuja) Dosha for given birth parameters.