Back to Docs

Match by Birth

Match by Birth

POST/api/v2/vedic/match

Calculate V2 Ashtakoota compatibility from two complete birth charts, including Moon placement resolution and dosha checks.

Authentication: send x-api-key.

Full URL

https://api.freeastroapi.com/api/v2/vedic/match
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

The birth-data-only compatibility contract: resolved person Moon details, Ashtakoota koota scores with evidence, Manglik/Nadi/Bhakoot dosha context, summary score, and metadata.

Example Request

curl -X POST "https://api.freeastroapi.com/api/v2/vedic/match" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
  "person1": {
    "year": 1990,
    "month": 5,
    "day": 15,
    "hour": 10,
    "minute": 30,
    "city": "New Delhi",
    "lat": 28.6139,
    "lng": 77.209,
    "ayanamsha": "lahiri",
    "house_system": "whole_sign",
    "node_type": "mean"
  },
  "person2": {
    "year": 1993,
    "month": 8,
    "day": 21,
    "hour": 14,
    "minute": 0,
    "city": "Mumbai",
    "lat": 19.076,
    "lng": 72.8777,
    "ayanamsha": "lahiri",
    "house_system": "whole_sign",
    "node_type": "mean"
  }
}'

Request Parameters

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

Field
person1
Type
object
Required
Yes
Description
Person 1 birth details using the same base Vedic birth fields.
Field
person2
Type
object
Required
Yes
Description
Person 2 birth details using the same base Vedic birth fields.
Field
person1.year
Type
integer
Required
Yes
Description
Person 1 birth year.
Field
person1.month
Type
integer
Required
Yes
Description
Person 1 birth month.
Field
person1.day
Type
integer
Required
Yes
Description
Person 1 birth day.
Field
person1.hour
Type
integer
Required
Yes
Description
Person 1 birth hour.
Field
person1.minute
Type
integer
Required
Yes
Description
Person 1 birth minute.
Field
person1.lat / person1.lng
Type
float
Required
No
Description
Person 1 coordinates. Recommended when available.
Field
person2.year
Type
integer
Required
Yes
Description
Person 2 birth year.
Field
person2.month
Type
integer
Required
Yes
Description
Person 2 birth month.
Field
person2.day
Type
integer
Required
Yes
Description
Person 2 birth day.
Field
person2.hour
Type
integer
Required
Yes
Description
Person 2 birth hour.
Field
person2.minute
Type
integer
Required
Yes
Description
Person 2 birth minute.
Field
person2.lat / person2.lng
Type
float
Required
No
Description
Person 2 coordinates. Recommended when available.

Response Shape

Field
persons
Type
array
Required
n/a
Description
Resolved person Moon sign and Nakshatra details. In Hindi, sign, Nakshatra and lord names are translated; input labels remain unchanged.
Field
persons[].label_display
Type
string
Required
n/a
Description
Hindi display value for generated labels such as Person 1. A client-supplied label is preserved verbatim.
Field
persons[].input_mode_label
Type
string
Required
n/a
Description
Hindi display label for input_mode. The manual or birth_chart code stays unchanged.
Field
ashtakoota
Type
object
Required
n/a
Description
Eight-koota score, percentage, stable recommendation value, and per-koota evidence.
Field
ashtakoota.recommendation_label
Type
string
Required
n/a
Description
Hindi display label for recommendation when language="hi". The English recommendation value remains stable.
Field
ashtakoota.kootas[].status_label
Type
string
Required
n/a
Description
Hindi display label for each stable status code. Koota names and rule-evidence messages are also translated.
Field
ashtakoota.kootas[].evidence[].kind_label
Type
string
Required
n/a
Description
Hindi display label for the stable evidence kind.
Field
doshas
Type
object
Required
n/a
Description
Manglik, Nadi, and Bhakoot dosha details. Human-readable messages are translated in Hindi.
Field
doshas.manglik.*.severity_label
Type
string
Required
n/a
Description
Hindi display label for Mangal Dosha severity. severity, severity_score and active remain stable.
Field
doshas.manglik.*.reference_frames[].frame_label
Type
string
Required
n/a
Description
Hindi display name for each stable Lagna or Moon reference-frame value.
Field
doshas.manglik.*.cancellations[].kind_label
Type
string
Required
n/a
Description
Hindi display label for each cancellation rule. Cancellation messages are translated too.
Field
doshas.manglik.compatibility.status_label
Type
string
Required
n/a
Description
Hindi display label for the stable Manglik compatibility status.
Field
summary
Type
object
Required
n/a
Description
Total score, traditional threshold, pass flag, and stable risk-flag codes.
Field
summary.risk_flag_labels
Type
array[string]
Required
n/a
Description
Hindi display labels aligned with risk_flags.
Field
summary.threshold_label
Type
string
Required
n/a
Description
Hindi explanation of whether the traditional minimum threshold was met.
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": {
    "year": 1990,
    "month": 5,
    "day": 15,
    "hour": 10,
    "minute": 30,
    "city": "New Delhi",
    "lat": 28.6139,
    "lng": 77.209,
    "ayanamsha": "lahiri",
    "house_system": "whole_sign",
    "node_type": "mean"
  },
  "person2": {
    "year": 1993,
    "month": 8,
    "day": 21,
    "hour": 14,
    "minute": 0,
    "city": "Mumbai",
    "lat": 19.076,
    "lng": 72.8777,
    "ayanamsha": "lahiri",
    "house_system": "whole_sign",
    "node_type": "mean"
  }
}

Real Response Example

V2

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

{
  "persons": [
    {
      "label": "Person 1",
      "input_mode": "birth_chart",
      "moon_sign": {
        "id": 9,
        "name": "Sagittarius",
        "degree": 29.8424
      },
      "moon_nakshatra": {
        "id": 21,
        "name": "Uttara Ashadha",
        "pada": 1,
        "lord": "Sun"
      }
    },
    {
      "label": "Person 2",
      "input_mode": "birth_chart",
      "moon_sign": {
        "id": 6,
        "name": "Virgo",
        "degree": 24.1171
      },
      "moon_nakshatra": {
        "id": 14,
        "name": "Chitra",
        "pada": 1,
        "lord": "Mars"
      }
    }
  ],
  "ashtakoota": {
    "score": 21,
    "max_score": 36,
    "percentage": 58.3,
    "recommendation": "Average Match",
    "kootas": [
      {
        "id": "varna",
        "name": "Varna",
        "score": 1,
        "max_score": 1,
        "status": "strong",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Person 1: Kshatriya; 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": 1.5,
        "max_score": 3,
        "status": "moderate",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Directional Tara scores are 0.0 and 1.5."
          }
        ]
      },
      {
        "id": "yoni",
        "name": "Yoni",
        "score": 2,
        "max_score": 4,
        "status": "moderate",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Person 1: Mongoose; Person 2: Tiger."
          }
        ]
      },
      {
        "id": "graha_maitri",
        "name": "Graha Maitri",
        "score": 0.5,
        "max_score": 5,
        "status": "weak",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Moon sign lords are Jupiter and Mercury; relations are enemy/neutral."
          }
        ]
      },
      {
        "id": "gana",
        "name": "Gana",
        "score": 0,
        "max_score": 6,
        "status": "dosha",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Person 1: Manushya; Person 2: Rakshasa."
          }
        ]
      },
      {
        "id": "bhakoot",
        "name": "Bhakoot",
        "score": 7,
        "max_score": 7,
        "status": "strong",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Moon signs are in 10/4 relation."
          }
        ]
      },
      {
        "id": "nadi",
        "name": "Nadi",
        "score": 8,
        "max_score": 8,
        "status": "strong",
        "evidence": [
          {
            "kind": "rule_evaluation",
            "message": "Person 1: Antya; Person 2: Madhya."
          }
        ]
      }
    ]
  },
  "doshas": {
    "manglik": {
      "person1": {
        "available": true,
        "active": true,
        "severity": "Low Mangal Dosha",
        "severity_score": 1,
        "reference_frames": [
          {
            "frame": "Lagna",
            "house": 8
          }
        ],
        "cancellations": [
          {
            "kind": "jupiter_aspect",
            "message": "Jupiter aspects Mars by Vedic graha drishti."
          }
        ],
        "message": "Low Mangal Dosha."
      },
      "person2": {
        "available": true,
        "active": true,
        "severity": "Low Mangal Dosha",
        "severity_score": 1,
        "reference_frames": [
          {
            "frame": "Moon",
            "house": 1
          }
        ],
        "cancellations": [
          {
            "kind": "jupiter_conjunction",
            "message": "Jupiter is conjoined Mars by sign."
          }
        ],
        "message": "Low Mangal Dosha."
      },
      "compatibility": {
        "available": true,
        "status": "balanced",
        "difference": 0,
        "message": "Mangal Dosha levels are balanced between both charts."
      }
    },
    "nadi": {
      "active": false,
      "score": 8,
      "max_score": 8,
      "message": "Nadi score is 8 out of 8."
    },
    "bhakoot": {
      "active": false,
      "score": 7,
      "max_score": 7,
      "message": "Bhakoot score is 7 out of 7."
    }
  },
  "summary": {
    "total_score": 21,
    "max_score": 36,
    "minimum_traditional_threshold": 18,
    "passes_minimum_threshold": true,
    "risk_flags": [
      "manglik_requires_review"
    ]
  },
  "metadata": {
    "endpoint_version": "v2",
    "ruleset_version": "astrosage_ashtakoota_v1",
    "calculation_basis": "moon_nakshatra_moon_rashi_ashtakoota",
    "person1_input_mode": "birth_chart",
    "person2_input_mode": "birth_chart"
  }
}

Related Docs

Manual compatibilityYoga detection