Kundali Matching API Guide 2025: Build Marriage Compatibility Apps

What is Kundali Matching?

Kundali matching (also called Kundli Milan or Horoscope Matching) is a Vedic astrology practice used to assess marriage compatibility between two individuals. It compares the birth charts (Kundalis) of the prospective bride and groom to determine their compatibility score.

The system analyzes planetary positions at the time of birth and calculates a Guna score out of 36. Higher scores indicate better compatibility. Most astrologers recommend a minimum score of 18 for marriage.

Ashtakoota (8 Koota) System Explained

The Ashtakoota system evaluates 8 different aspects of compatibility:

API Integration Guide

Vedika API provides a comprehensive Kundali matching endpoint:

POST https://api.vedika.io/v1/compatibility/kundali-matching

{
  "person1": {
    "name": "Bride Name",
    "dateOfBirth": "1995-03-15",
    "timeOfBirth": "10:30:00",
    "placeOfBirth": "Mumbai, India"
  },
  "person2": {
    "name": "Groom Name",
    "dateOfBirth": "1993-07-22",
    "timeOfBirth": "14:45:00",
    "placeOfBirth": "Delhi, India"
  },
  "ayanamsa": "lahiri"
}

API Response

{
  "totalScore": 28,
  "maxScore": 36,
  "percentage": 77.8,
  "recommendation": "Good Match",
  "ashtakoota": {
    "varna": {"score": 1, "max": 1, "description": "Compatible"},
    "vashya": {"score": 2, "max": 2, "description": "Strong attraction"},
    "tara": {"score": 3, "max": 3, "description": "Favorable destiny"},
    "yoni": {"score": 3, "max": 4, "description": "Good compatibility"},
    "grahaMaitri": {"score": 5, "max": 5, "description": "Excellent mental match"},
    "gana": {"score": 6, "max": 6, "description": "Perfect temperament"},
    "bhakoot": {"score": 5, "max": 7, "description": "Minor concerns"},
    "nadi": {"score": 3, "max": 8, "description": "Nadi Dosha present"}
  },
  "doshas": {
    "mangalDosha": {"person1": false, "person2": true, "cancelled": true},
    "nadiDosha": {"present": true, "severity": "medium", "remedies": [...]}
  }
}

Code Examples

Python

import requests

response = requests.post(
    "https://api.vedika.io/v1/compatibility/kundali-matching",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "person1": {
            "dateOfBirth": "1995-03-15",
            "timeOfBirth": "10:30:00",
            "placeOfBirth": "Mumbai, India"
        },
        "person2": {
            "dateOfBirth": "1993-07-22",
            "timeOfBirth": "14:45:00",
            "placeOfBirth": "Delhi, India"
        }
    }
)

result = response.json()
print(f"Compatibility: {result['totalScore']}/36 ({result['percentage']}%)")
print(f"Recommendation: {result['recommendation']}")

Node.js

const response = await fetch('https://api.vedika.io/v1/compatibility/kundali-matching', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    person1: { dateOfBirth: '1995-03-15', timeOfBirth: '10:30:00', placeOfBirth: 'Mumbai, India' },
    person2: { dateOfBirth: '1993-07-22', timeOfBirth: '14:45:00', placeOfBirth: 'Delhi, India' }
  })
});

const result = await response.json();
console.log(`Score: ${result.totalScore}/36`);

Handling Doshas

The API automatically detects and analyzes common doshas:

• Mangal Dosha (Kuja Dosha) - Mars placement issues
• Nadi Dosha - Same Nadi category (health concerns)
• Bhakoot Dosha - Unfavorable Moon sign combination
• Gana Dosha - Temperament mismatch

The API also returns dosha cancellation rules - traditional exceptions that nullify the negative effects.

Best Practices for Matrimony Apps

1. Cache birth chart calculations - Calculate once, reuse for multiple matches
2. Show detailed breakdowns - Users trust transparent scoring
3. Explain doshas clearly - Include remedies and cancellation rules
4. Allow ayanamsa selection - Different traditions prefer different systems
5. Provide AI interpretation - Use Vedika's chatbot for personalized insights