Planetary Dasha System APIs

1. Vimshottari & Major Dasha Systems

1. Name

Vimshottari & Major Dasha Systems

2. Purpose

Calculates Vimshottari Dasha, Yogini Dasha, Ashtottari Dasha, Kalachakra Dasha, and Jaimini Chara Dasha timeline trees (Mahadasha, Antardasha, Pratyantardasha) from native Moon longitude. Used by frontend for timeline/Dasha views.

3. Endpoint

POST /api/v1/dashas/{dasha_type}

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,
  "lang": "en"
}

7. Request Params Table

Field	Type	Required	Description	Allowed Values	Validation	Example
`dasha_type`	string	Yes (Path)	Dasha system key in URL path	`vimshottari`, `yogini`, `ashtottari`, `kalachakra`, `conditional`	Path Segment	`"vimshottari"`
`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 VIMSHOTTARI dasha successfully",
  "data": {
    "dasha_type": "VIMSHOTTARI",
    "current": {
      "mahadasha": "Sun",
      "antardasha": "Saturn"
    },
    "timeline": [
      {
        "planet": "Sun",
        "start_date": "1983-10-01",
        "end_date": "1989-10-01",
        "duration_years": 6
      }
    ]
  }
}

10. Response Fields Table

Field	Type	Description	Nullable	Example
`status`	string	Result status	No	`"success"`
`message`	string	Human readable message	No	`"Calculated VIMSHOTTARI dasha successfully"`
`data.dasha_type`	string	Active Dasha calculation mode	No	`"VIMSHOTTARI"`
`data.current.mahadasha`	string	Active ruling Mahadasha planet	Yes	`"Sun"`
`data.current.antardasha`	string	Active ruling Antardasha planet	Yes	`"Saturn"`
`data.timeline[].planet`	string	Dasha lord planet name	No	`"Sun"`
`data.timeline[].start_date`	string	Period start date (`YYYY-MM-DD`)	No	`"1983-10-01"`
`data.timeline[].end_date`	string	Period end date (`YYYY-MM-DD`)	No	`"1989-10-01"`
`data.timeline[].duration_years`	float	Total period length in solar years	No	`6`

11. Status Codes Table

Code	Meaning	When Returned
`200`	OK	Dasha timeline generated.
`400`	Bad Request	Invalid Dasha type in path.
`500`	Internal Error	Calculation error.

12. Error Examples

{
  "status": "error",
  "message": "Invalid Dasha requested: INVALID. Valid options: vimshottari, yogini, ashtottari, kalachakra, conditional",
  "data": null
}

Explanation: Client requested an unsupported Dasha system.

13. Frontend Usage Notes

Render the timeline array as an interactive timeline component or accordion list.

14. Validation Rules

dasha_type path parameter must match allowed enum values.

15. Business Rules

Vimshottari Dasha spans a total 120-year cycle starting from the native's birth Nakshatra balance.

16. Security Notes

Standard public API endpoint.

17. Performance Notes

Fast (~35ms).

POST /api/v1/chart
POST /api/v1/chara-dasha

19. Example Frontend Flow

User clicks "Dasha Timelines" tab.
UI calls /api/v1/dashas/vimshottari.
UI highlights current active Mahadasha and Antardasha.

20. Complete Example

Request:

POST /api/v1/dashas/vimshottari 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 VIMSHOTTARI dasha successfully",
  "data": {
    "dasha_type": "VIMSHOTTARI",
    "current": { "mahadasha": "Sun", "antardasha": "Saturn" },
    "timeline": [{ "planet": "Sun", "start_date": "1983-10-01", "end_date": "1989-10-01" }]
  }
}

Explanation: Returns active Dasha periods and timeline.