Basics & Birth Chart APIs

1. Full Natal Chart (Birth Chart)

1. Name

Full Natal Chart (Birth Chart)

2. Purpose

Calculates the complete Vedic Birth Chart (Horoscope / Janam Kundali) including Lagna (Ascendant), all planetary longitudes, house cusps, Nakshatra padas, planetary dignities, and full AI/deterministic interpretation report. Called by the frontend on initial chart generation or user profile view.

3. Endpoint

POST /api/v1/chart

4. Auth

Type: None or API Key (Optional header depending on subscription tier) 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 rate-limited tier access.

6. Request Payload

{
  "name": "Santhosh Murthy R",
  "datetime": "1983-10-01T20:50",
  "timezone": "Asia/Kolkata",
  "latitude": 11.3410,
  "longitude": 77.7172,
  "lang": "en",
  "config": {
    "ayanamsa": "LAHIRI",
    "house_system": "WHOLE_SIGN"
  }
}

7. Request Params Table

Field	Type	Required	Description	Allowed Values	Validation	Example
`name`	string	Yes	Full name of the subject	String	Max 200 characters	`"Santhosh Murthy R"`
`datetime`	string	Yes	Birth date and local time	ISO 8601 string	`YYYY-MM-DDTHH:MM`	`"1983-10-01T20:50"`
`timezone`	string	Yes	IANA Timezone identifier	Valid IANA TZ	Standard timezone string	`"Asia/Kolkata"`
`latitude`	float	Yes	Geographic latitude	`-90.0` to `+90.0`	Numeric float	`11.3410`
`longitude`	float	Yes	Geographic longitude	`-180.0` to `+180.0`	Numeric float	`77.7172`
`lang`	string	No	Language code for report	`"en"`, `"hi"`, `"ta"`	Default: `"en"`	`"en"`
`config.ayanamsa`	string	No	Precession calculation mode	`"LAHIRI"`, `"RAMAN"`, `"KP"`	Default: `"LAHIRI"`	`"LAHIRI"`
`config.house_system`	string	No	House calculation system	`"WHOLE_SIGN"`, `"PLACIDUS"`	Default: `"WHOLE_SIGN"`	`"WHOLE_SIGN"`

8. Request Example

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

9. Success Response

Status: 200 OK

{
  "status": "success",
  "message": "Chart calculated successfully",
  "data": {
    "chart": {
      "lagna": {
        "sign_id": 4,
        "sign_name": "Taurus",
        "longitude": 45.32,
        "degree": 15.32
      },
      "planets": [
        {
          "id": "Sun",
          "name": "Sun",
          "longitude": 164.21,
          "sign_id": 6,
          "sign_name": "Virgo",
          "house": 5,
          "nakshatra": "Hasta",
          "pada": 2,
          "is_retrograde": false,
          "dignity": "Own"
        }
      ],
      "houses": []
    },
    "report": {
      "general": [],
      "planets": [],
      "dashas": []
    }
  }
}

10. Response Fields Table

Field	Type	Description	Nullable	Example
`status`	string	Execution result status	No	`"success"`
`message`	string	Human readable response message	No	`"Chart calculated successfully"`
`data.chart.lagna.sign_id`	integer	Zodiac sign ID (1=Aries to 12=Pisces)	No	`4`
`data.chart.lagna.sign_name`	string	English zodiac sign name	No	`"Taurus"`
`data.chart.lagna.longitude`	float	Absolute tropical/sidereal longitude	No	`45.32`
`data.chart.planets[].id`	string	Unique planet key identifier	No	`"Sun"`
`data.chart.planets[].name`	string	Display name of planet	No	`"Sun"`
`data.chart.planets[].longitude`	float	Sidereal longitude in degrees	No	`164.21`
`data.chart.planets[].house`	integer	House placement (1 to 12)	No	`5`
`data.chart.planets[].nakshatra`	string	Name of Nakshatra occupied	No	`"Hasta"`
`data.chart.planets[].pada`	integer	Nakshatra Pada quarter (1 to 4)	No	`2`
`data.chart.planets[].is_retrograde`	boolean	True if planet is in retrograde motion	No	`false`
`data.chart.planets[].dignity`	string	Astrological dignity status	No	`"Own"`

11. Status Codes Table

Code	Meaning	When Returned
`200`	OK	Chart calculated successfully.
`400`	Bad Request	Invalid JSON structure or missing required parameters.
`422`	Unprocessable Entity	Out of range latitude/longitude or unparseable date/timezone.
`500`	Internal Server Error	Ephemeris calculation exception.

12. Error Examples

{
  "status": "error",
  "message": "Missing required field: 'datetime'."
}

Explanation: The client omitted the mandatory datetime field in the JSON request body.

13. Frontend Usage Notes

Call this endpoint when initializing a user's dashboard chart view.
Cache the response locally (in localStorage or IndexedDB) keyed by subject name + datetime to avoid duplicate API calls.
Display a loading spinner during API invocation as Swiss Ephemeris calculations require 50-150ms.

14. Validation Rules

name: max length 200 chars.
latitude: -90.0 to +90.0.
longitude: -180.0 to +180.0.
datetime: Valid ISO format YYYY-MM-DDTHH:MM.

15. Business Rules

Uses Lahiri (Chitra Paksha) Ayanamsa by default for sidereal positioning.
Calculates 9 Grahas: Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu.

16. Security Notes

No sensitive user PII is persisted during chart calculation.
Rate-limited per IP / API key.

17. Performance Notes

Average response time: ~80ms.
Cached in APCu when caching headers are present.

POST /api/v1/chart/planets
POST /api/v1/predict

19. Example Frontend Flow

User enters birth date, time, location in form.
App sends POST /api/v1/chart.
App receives JSON and renders Natal Wheel and Interpretation summary.

20. Complete Example

Request:

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

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

Response:

{
  "status": "success",
  "message": "Chart calculated successfully",
  "data": {
    "chart": {
      "lagna": { "sign_id": 2, "sign_name": "Taurus", "longitude": 45.32 },
      "planets": [
        { "id": "Sun", "name": "Sun", "longitude": 164.21, "house": 5, "nakshatra": "Hasta", "pada": 2, "is_retrograde": false }
      ]
    }
  }
}

Explanation: Calculates and returns Taurus Lagna at 45.32° with Sun in 5th house in Hasta Nakshatra.

2. Transit & Sade Sati Predictions

1. Name

Transit & Sade Sati Predictions

2. Purpose

Calculates real-time planetary transits (Gochar) and Saturn Sade Sati status for a specific target date relative to the native's Moon sign. Used by frontend for daily/yearly prediction screens.

3. Endpoint

POST /api/v1/predict

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,
  "transit_date": "2026-07-27T12:00",
  "lang": "en"
}

7. Request Params Table

Field	Type	Required	Description	Allowed Values	Validation	Example
`name`	string	Yes	Subject name	String	Max 200 chars	`"Santhosh"`
`datetime`	string	Yes	Birth local datetime	ISO string	`YYYY-MM-DDTHH:MM`	`"1983-10-01T20:50"`
`timezone`	string	Yes	IANA timezone	Valid IANA TZ	Valid string	`"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`
`transit_date`	string	Yes	Target transit date to evaluate	ISO string	`YYYY-MM-DDTHH:MM`	`"2026-07-27T12:00"`
`lang`	string	No	Report language	`"en"`, `"hi"`, `"ta"`	Default: `"en"`	`"en"`

8. Request Example

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

9. Success Response

Status: 200 OK

{
  "status": "success",
  "message": "Prediction calculated successfully",
  "data": {
    "transits": {
      "sade_sati": {
        "is_active": true,
        "phase": "Peak Phase",
        "house_from_moon": 1
      },
      "transits": [
        { "id": "JU", "name": "Jupiter", "house_from_moon": 1 }
      ]
    },
    "forecast": {
      "general": [
        { "title": "Major Transit: Jupiter", "text": "Currently, Jupiter is transiting the 1 house relative to your natal Moon..." }
      ]
    }
  }
}

10. Response Fields Table

Field	Type	Description	Nullable	Example
`status`	string	Request status	No	`"success"`
`data.transits.sade_sati.is_active`	boolean	True if native is in Sade Sati phase	No	`true`
`data.transits.sade_sati.phase`	string	Name of current Sade Sati phase	Yes	`"Peak Phase"`
`data.transits.sade_sati.house_from_moon`	integer	Transit house distance relative to natal Moon	No	`1`
`data.forecast.general[].title`	string	Prediction title	No	`"Major Transit: Jupiter"`
`data.forecast.general[].text`	string	Detailed astrological prediction text	No	`"Currently, Jupiter is transiting..."`

11. Status Codes Table

Code	Meaning	When Returned
`200`	OK	Transit evaluation successful.
`400`	Bad Request	Missing `transit_date` or birth details.
`422`	Unprocessable Entity	Invalid date or location coordinates.
`500`	Internal Error	Calculation error.

12. Error Examples

{
  "status": "error",
  "message": "Missing required field: 'transit_date'."
}

Explanation: The client called /predict without providing transit_date.

13. Frontend Usage Notes

Call this endpoint when the user selects a target date on a horoscope/prediction tab.
Pass transit_date defaulted to new Date().toISOString().

14. Validation Rules

Requires transit_date in valid ISO string format.

15. Business Rules

Sade Sati is active when Saturn transits the 12th, 1st, or 2nd house from natal Moon.

16. Security Notes

Standard API Key security applies.

17. Performance Notes

Fast calculation time (~60ms).

POST /api/v1/chart
POST /api/v1/dashas/vimshottari

19. Example Frontend Flow

User opens Predictions tab.
UI calls /api/v1/predict with today's date.
UI renders Sade Sati warning badge and major planet transit predictions.

20. Complete Example

Request:

POST /api/v1/predict 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,
  "transit_date": "2026-07-27T12:00"
}

Response:

{
  "status": "success",
  "message": "Prediction calculated successfully",
  "data": {
    "transits": { "sade_sati": { "is_active": true } },
    "forecast": { "general": [{ "title": "Sade Sati", "text": "Active 1st phase..." }] }
  }
}

Explanation: Calculates Sade Sati and transit predictions for July 27, 2026.

Basics & Birth Chart APIs

1. Full Natal Chart (Birth Chart)

1. Name

2. Purpose

3. Endpoint

4. Auth

5. Request Headers

6. Request Payload

7. Request Params Table

8. Request Example

9. Success Response

10. Response Fields Table

11. Status Codes Table

12. Error Examples

13. Frontend Usage Notes

14. Validation Rules

15. Business Rules

16. Security Notes

17. Performance Notes

18. Related APIs

19. Example Frontend Flow

20. Complete Example

2. Transit & Sade Sati Predictions

1. Name

2. Purpose

3. Endpoint

4. Auth

5. Request Headers

6. Request Payload

7. Request Params Table

8. Request Example

9. Success Response

10. Response Fields Table

11. Status Codes Table

12. Error Examples

13. Frontend Usage Notes

14. Validation Rules

15. Business Rules

16. Security Notes

17. Performance Notes

18. Related APIs

19. Example Frontend Flow

20. Complete Example