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.
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": {
    "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

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": "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