Compatibility & Matchmaking APIs

1. Ashtakoota Matchmaking & Compatibility Analysis

1. Name

Ashtakoota Matchmaking & Compatibility Analysis

2. Purpose

Performs complete Vedic Ashtakoota Gunamilan (36-point compatibility scoring) between Boy and Girl, including 8 Kuta scores (Varna, Vashya, Tara, Yoni, Graha Maitri, Gana, Bhakoot, Nadi), Nadi/Bhakoot Dosha checks, and overall compatibility verdict. Used by wedding/matrimonial portals.

3. Endpoint

POST /api/v1/match/{sub_endpoint} or POST /api/v1/match

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,
  "p_name": "Partner",
  "p_datetime": "1985-05-15T10:30",
  "p_timezone": "Asia/Kolkata",
  "p_latitude": 12.9716,
  "p_longitude": 77.5946
}

7. Request Params Table

Field Type Required Description Allowed Values Validation Example
sub_endpoint string No (Path) Matching mode ashtakoota, manglik, reports, marriage-analysis Path Segment "ashtakoota"
name string Yes Primary subject name String Max 200 chars "Santhosh"
datetime string Yes Primary subject local birth datetime ISO string YYYY-MM-DDTHH:MM "1983-10-01T20:50"
timezone string Yes Primary subject IANA timezone Valid IANA TZ Valid TZ string "Asia/Kolkata"
latitude float Yes Primary subject latitude -90.0 to +90.0 Float 11.3410
longitude float Yes Primary subject longitude -180.0 to +180.0 Float 77.7172
p_name string Yes Partner subject name String Max 200 chars "Partner"
p_datetime string Yes Partner local birth datetime ISO string YYYY-MM-DDTHH:MM "1985-05-15T10:30"
p_timezone string Yes Partner IANA timezone Valid IANA TZ Valid TZ string "Asia/Kolkata"
p_latitude float Yes Partner latitude -90.0 to +90.0 Float 12.9716
p_longitude float Yes Partner longitude -180.0 to +180.0 Float 77.5946

8. Request Example

{
  "name": "Santhosh Murthy R",
  "datetime": "1983-10-01T20:50",
  "timezone": "Asia/Kolkata",
  "latitude": 11.3410,
  "longitude": 77.7172,
  "p_name": "Partner",
  "p_datetime": "1985-05-15T10:30",
  "p_timezone": "Asia/Kolkata",
  "p_latitude": 12.9716,
  "p_longitude": 77.5946
}

9. Success Response

Status: 200 OK

{
  "status": "success",
  "message": "Matchmaking calculation complete",
  "data": {
    "total_score": 28.5,
    "max_score": 36,
    "verdict": "EXCELLENT",
    "kutas": {
      "varna": { "obtained": 1, "max": 1 },
      "vashya": { "obtained": 2, "max": 2 },
      "tara": { "obtained": 3, "max": 3 },
      "yoni": { "obtained": 3, "max": 4 },
      "graha_maitri": { "obtained": 5, "max": 5 },
      "gana": { "obtained": 6, "max": 6 },
      "bhakoot": { "obtained": 7, "max": 7 },
      "nadi": { "obtained": 8, "max": 8 }
    }
  }
}

10. Response Fields Table

Field Type Description Nullable Example
status string Result status No "success"
data.total_score float Total Guna score obtained out of 36 No 28.5
data.max_score float Maximum possible Guna score No 36
data.verdict string Compatibility assessment (POOR, AVERAGE, GOOD, EXCELLENT) No "EXCELLENT"
data.kutas.nadi.obtained float Score obtained for Nadi Kuta No 8
data.kutas.nadi.max float Max possible score for Nadi Kuta No 8

11. Status Codes Table

Code Meaning When Returned
200 OK Match calculation complete.
400 Bad Request Missing primary or partner birth data.
500 Internal Error Calculation error.

12. Error Examples

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

13. Frontend Usage Notes

14. Validation Rules

15. Business Rules

16. Security Notes

17. Performance Notes

19. Example Frontend Flow

  1. User enters Primary and Partner details in Match form.
  2. App sends POST /api/v1/match.
  3. App displays 36-point compatibility gauge.

20. Complete Example

Request:

POST /api/v1/match 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,
  "p_name": "Partner",
  "p_datetime": "1985-05-15T10:30",
  "p_timezone": "Asia/Kolkata",
  "p_latitude": 12.9716,
  "p_longitude": 77.5946
}

Response:

{
  "status": "success",
  "message": "Matchmaking calculation complete",
  "data": { "total_score": 28.5, "max_score": 36, "verdict": "EXCELLENT" }
}

Explanation: Evaluates compatibility between Santhosh and Partner.

2. Nakshatra Match Finder & Star Lookup

1. Name

Nakshatra Match Finder & Star Lookup

2. Purpose

Given a Boy's or Girl's Nakshatra (1–27) and Pada (1–4), finds all matching stars and Padas that pass the 8 Ashtakoota Kuta scores (Varna, Vashya, Tara, Yoni, Graha Maitri, Gana, Bhakoot, Nadi) without needing exact birth datetime or geographical coordinates. Categorizes recommendations into Best, Good, and Average stars.

3. Endpoint

POST /api/v1/match/nakshatra or POST /api/v1/match/star-finder

4. Auth

Type: None / API Key
Header Example: X-API-Key: sk_live_5f6f2e0a690a45fae957c026cbd820c83bb55461bfad3b94

5. Request Payload

{
  "gender": "boy",
  "nakshatra_id": 8,
  "pada": 1,
  "min_score": 18.0
}

Or 1-on-1 direct Nakshatra evaluation:

{
  "male_nakshatra_id": 8,
  "male_pada": 1,
  "female_nakshatra_id": 4,
  "female_pada": 2
}

6. Request Params Table

Field Type Required Description Allowed Values Example
gender string Optional Subject gender "boy", "girl", "male", "female" "boy"
nakshatra_id integer/string Yes Nakshatra ID (1–27) or Nakshatra Name 1 to 27 or "Pushya" 8
pada integer Optional Nakshatra Pada 1, 2, 3, 4 (Default: 1) 1
min_score float Optional Minimum Ashtakoota score threshold 0.0 to 36.0 (Default: 18.0) 18.0

7. Success Response Example

Status: 200 OK

{
  "status": "success",
  "message": "Nakshatra matching stars calculated successfully",
  "data": {
    "input": {
      "gender": "boy",
      "nakshatra_id": 8,
      "nakshatra_name": "Pushya",
      "pada": 1,
      "sign_id": 4,
      "sign_name": "Cancer"
    },
    "summary": {
      "best_matches": 12,
      "good_matches": 16,
      "average_matches": 14,
      "total_filtered": 42
    },
    "matches": {
      "best": [
        {
          "nakshatra_id": 3,
          "nakshatra_name": "Krittika",
          "pada": 2,
          "sign_id": 2,
          "sign_name": "Taurus",
          "total_score": 30.5,
          "max_score": 36.0,
          "match_percentage": 84.72,
          "verdict": "Excellent",
          "doshas": {
            "nadi_dosha": false,
            "bhakoot_dosha": false,
            "gana_dosha": false
          },
          "kutas": {
            "varna": { "score": 1, "max": 1 },
            "vashya": { "score": 2, "max": 2 },
            "tara": { "score": 3, "max": 3 },
            "yoni": { "score": 3.5, "max": 4 },
            "maitri": { "score": 5, "max": 5 },
            "gana": { "score": 6, "max": 6 },
            "bhakoot": { "score": 7, "max": 7 },
            "nadi": { "score": 8, "max": 8 }
          }
        }
      ],
      "good": [],
      "average": []
    }
  }
}

8. Match Categorization Rules