Numerology APIs

1. Numerology Calculations (Life Path, Destiny, Soul Urge, Personality, Lo Shu Grid)

1. Name

Numerology Calculations (Life Path, Destiny, Soul Urge, Personality, Lo Shu Grid)

2. Purpose

Calculates Pythogorean and Chaldean numerology metrics including Life Path Number, Destiny Number (Expression), Soul Urge Number (Heart's Desire), Personality Number, and the 3x3 Lo Shu Grid layout. Used by frontend for numerology analysis screens.

3. Endpoint

POST /api/v1/numerology/{numerology_type} or POST /api/v1/numerology

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
`numerology_type`	string	No (Path)	Numerology mode key in URL path	`life-path`, `destiny-number`, `soul-urge`, `personality-number`, `lo-shu-grid`	Path Segment	`"life-path"`
`name`	string	Yes	Full name of subject (used for Chaldean/Pythagorean letter values)	String	Max 200 chars	`"Santhosh Murthy R"`
`datetime`	string	Yes	Date of birth	ISO string	`YYYY-MM-DDTHH:MM`	`"1983-10-01T20:50"`

8. Request Example

{
  "name": "Santhosh Murthy R",
  "datetime": "1983-10-01T20:50"
}

9. Success Response

Status: 200 OK

{
  "status": "success",
  "message": "Calculated LIFE-PATH numerology successfully",
  "data": {
    "life_path_number": 5,
    "ruling_planet": "Mercury",
    "description": "Life Path 5 indicates freedom, versatility, adventure, and adaptability."
  }
}

10. Response Fields Table

Field	Type	Description	Nullable	Example
`status`	string	Result status	No	`"success"`
`message`	string	Result message	No	`"Calculated LIFE-PATH numerology successfully"`
`data.life_path_number`	integer	Reduced single digit or Master Number (1-9, 11, 22, 33)	No	`5`
`data.ruling_planet`	string	Ruling planet associated with number	No	`"Mercury"`
`data.description`	string	Behavioral interpretation	No	`"Life Path 5 indicates..."`

11. Status Codes Table

Code	Meaning	When Returned
`200`	OK	Numerology calculation successful.
`400`	Bad Request	Missing name or birthdate.
`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

Render the 3x3 Lo Shu Grid for /numerology/lo-shu-grid.

14. Validation Rules

name is required for letter-value reductions.

15. Business Rules

Master Numbers 11, 22, and 33 are not reduced to single digits.

16. Security Notes

Standard public endpoint.

17. Performance Notes

Fast (< 15ms).

POST /api/v1/chart

19. Example Frontend Flow

User clicks "Numerology" tab.
App sends POST /api/v1/numerology.
App displays numbers and Lo Shu Grid.

20. Complete Example

Request:

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

{
  "name": "Santhosh Murthy R",
  "datetime": "1983-10-01T20:50"
}

Response:

{
  "status": "success",
  "message": "Calculated LIFE-PATH numerology successfully",
  "data": { "life_path_number": 5, "ruling_planet": "Mercury" }
}

Explanation: Calculates Life Path Number 5 for birthdate 1983-10-01.