Back to Docs

Compatibility

Compatibility

POST/api/v2/vedic/compatibility

Calculate V2 Ashtakoota compatibility from structured manual Moon details, legacy flat Moon fields, or two full birth charts.

Authentication: send x-api-key.

Full URL

https://api.freeastroapi.com/api/v2/vedic/compatibility
Safe retries with Idempotency-Key

Authenticated, billable astrology POST requests accept the optional header Idempotency-Key: <client-generated unique operation key>. Reuse the same key only when retrying the exact same method, path, query string, and JSON body after a timeout or network failure.

A completed replay returns the first response with Idempotency-Replayed: true, does not rerun the calculation, and does not consume extra quota. Keys are retained for about 24 hours.

Reusing a key with a changed request returns 409 idempotency_key_reused. A duplicate while the first request is still running returns 409 request_in_progress with Retry-After.

What It Returns

A compatibility payload with resolved Moon details, Ashtakoota koota-by-koota scores and evidence, dosha checks, summary scoring, and input-mode metadata. Use /match when both complete birth details are available.

Example Request

curl -X POST "https://api.freeastroapi.com/api/v2/vedic/compatibility" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
  "person1_moon": {
    "label": "Person 1",
    "moon_nakshatra": 22,
    "moon_sign": 10,
    "moon_degree": 14.2,
    "moon_pada": 2
  },
  "person2_moon": {
    "label": "Person 2",
    "moon_nakshatra": 13,
    "moon_sign": 6,
    "moon_degree": 8.5,
    "moon_pada": 3
  }
}'

Request Parameters

Provide either city or both lat and lng. Coordinates are recommended for stable production results.

Field
person1
Type
object
Required
No
Description
Optional Person 1 birth details. Use with person2 for birth-chart mode.
Field
person2
Type
object
Required
No
Description
Optional Person 2 birth details. Use with person1 for birth-chart mode.
Field
person1_moon
Type
object
Required
No
Description
Structured manual Moon details for Person 1.
Field
person2_moon
Type
object
Required
No
Description
Structured manual Moon details for Person 2.
Field
person1_moon.moon_nakshatra
Type
integer
Required
No
Description
Moon Nakshatra ID, 1-27.
Field
person1_moon.moon_sign
Type
integer
Required
No
Description
Moon sign ID, 1-12.
Field
person1_moon.moon_degree
Type
float
Required
No
Description
Moon degree inside sign, 0 <= degree < 30.
Field
person1_moon.moon_pada
Type
integer
Required
No
Description
Nakshatra pada, 1-4.
Field
person2_moon.moon_nakshatra
Type
integer
Required
No
Description
Moon Nakshatra ID, 1-27.
Field
person2_moon.moon_sign
Type
integer
Required
No
Description
Moon sign ID, 1-12.
Field
person2_moon.moon_degree
Type
float
Required
No
Description
Moon degree inside sign, 0 <= degree < 30.
Field
person2_moon.moon_pada
Type
integer
Required
No
Description
Nakshatra pada, 1-4.
Field
person1_moon_nakshatra / person2_moon_nakshatra
Type
integer
Required
No
Description
Legacy flat manual Moon fields remain accepted for compatibility.
Field
person1_moon_sign / person2_moon_sign
Type
integer
Required
No
Description
Legacy flat Moon sign fields remain accepted for compatibility.

Response Shape

Field
persons
Type
array
Required
n/a
Description
Resolved person Moon sign and Nakshatra details.
Field
ashtakoota
Type
object
Required
n/a
Description
Eight-koota score, percentage, recommendation, and per-koota evidence.
Field
doshas
Type
object
Required
n/a
Description
Manglik, Nadi, and Bhakoot dosha details.
Field
summary
Type
object
Required
n/a
Description
Total score, traditional threshold, pass flag, and risk flags.
Field
metadata
Type
object
Required
n/a
Description
Endpoint version, ruleset, calculation basis, and input modes.

Real Request Example

This request was captured from the live production endpoint and is the same payload used in the code tabs.

{
  "person1_moon": {
    "label": "Person 1",
    "moon_nakshatra": 22,
    "moon_sign": 10,
    "moon_degree": 14.2,
    "moon_pada": 2
  },
  "person2_moon": {
    "label": "Person 2",
    "moon_nakshatra": 13,
    "moon_sign": 6,
    "moon_degree": 8.5,
    "moon_pada": 3
  }
}

Real Response Example

This is a real production response for the example payload. Large arrays are intentionally shown as returned by the API.

V2
{
  "persons": [
    {
      "label": "Person 1",
      "input_mode": "manual",
      "moon_sign": {
        "id": 10,
        "name": "Capricorn",
        "degree": 14.2
      },
      "moon_nakshatra": {
        "id": 22,
        "name": "Shravana",
        "pada": 2,
        "lord": "Moon"
      }
    },
    {
      "label": "Person 2",
      "input_mode": "manual",
      "moon_sign": {
        "id": 6,
        "name": "Virgo",
        "degree": 8.5
      },
      "moon_nakshatra": {
        "id": 13,
        "name": "Hasta",
        "pada": 3,
        "lord": "Moon"
      }
    }
  ],
  "ashtakoota": {
    "score": 25,
    "max_score": 36,
    "percentage": 69.4,
    "recommendation": "Good Match",
    "kootas": [
      {
        "id": "varna",
        "name": "Varna",
        "score": 1,
        "max_score": 1,
        "status": "strong",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Person 1: Vaishya; Person 2: Vaishya."
          }
        ]
      },
      {
        "id": "vashya",
        "name": "Vashya",
        "score": 1,
        "max_score": 2,
        "status": "moderate",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Person 1: Quadruped; Person 2: Human."
          }
        ]
      },
      {
        "id": "tara",
        "name": "Tara",
        "score": 3,
        "max_score": 3,
        "status": "strong",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Directional Tara scores are 1.5 and 1.5."
          }
        ]
      },
      {
        "id": "yoni",
        "name": "Yoni",
        "score": 2,
        "max_score": 4,
        "status": "moderate",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Person 1: Monkey; Person 2: Buffalo."
          }
        ]
      },
      {
        "id": "graha_maitri",
        "name": "Graha Maitri",
        "score": 4,
        "max_score": 5,
        "status": "strong",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Moon sign lords are Saturn and Mercury; relations are friend/neutral."
          }
        ]
      },
      {
        "id": "gana",
        "name": "Gana",
        "score": 6,
        "max_score": 6,
        "status": "strong",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Person 1: Deva; Person 2: Deva."
          }
        ]
      },
      {
        "id": "bhakoot",
        "name": "Bhakoot",
        "score": 0,
        "max_score": 7,
        "status": "dosha",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Moon signs are in 9/5 relation."
          }
        ]
      },
      {
        "id": "nadi",
        "name": "Nadi",
        "score": 8,
        "max_score": 8,
        "status": "strong",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Person 1: Antya; Person 2: Adi."
          }
        ]
      }
    ]
  },
  "doshas": {
    "manglik": {
      "person1": {
        "available": false,
        "active": null,
        "severity": null,
        "severity_score": null,
        "reference_frames": [],
        "cancellations": [],
        "message": "Manglik evaluation requires birth-chart input."
      },
      "person2": {
        "available": false,
        "active": null,
        "severity": null,
        "severity_score": null,
        "reference_frames": [],
        "cancellations": [],
        "message": "Manglik evaluation requires birth-chart input."
      },
      "compatibility": {
        "available": false,
        "status": "unknown",
        "message": "Manglik compatibility requires birth-chart input for both people."
      }
    },
    "nadi": {
      "active": false,
      "score": 8,
      "max_score": 8,
      "message": "Nadi score is 8 out of 8."
    },
    "bhakoot": {
      "active": true,
      "score": 0,
      "max_score": 7,
      "message": "Bhakoot score is 0 out of 7."
    }
  },
  "summary": {
    "total_score": 25,
    "max_score": 36,
    "minimum_traditional_threshold": 18,
    "passes_minimum_threshold": true,
    "risk_flags": [
      "bhakoot_dosha"
    ]
  },
  "metadata": {
    "endpoint_version": "v2",
    "ruleset_version": "astrosage_ashtakoota_v1",
    "calculation_basis": "moon_nakshatra_moon_rashi_ashtakoota",
    "person1_input_mode": "manual",
    "person2_input_mode": "manual"
  }
}

Related Docs

Match by birthBasic Vedic chart