Matchmaking API Guide: Kundli Matching for Matrimonial Apps

Why Kundli Matching Matters

In India, 75% of marriages involve astrological compatibility checks. Matrimonial platforms that offer Kundli matching see 3x higher engagement and premium subscription conversions.

The 36 Gunas (Ashtakoota)

Ashtakoota matching evaluates 8 categories with a total of 36 points:

Basic Kundli Matching API

// Match two birth charts
const response = await fetch('https://api.vedika.io/v2/astrology/match/kundli', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
        male: {
            datetime: '1992-08-15T06:30:00+05:30',
            latitude: 28.6139,
            longitude: 77.2090
        },
        female: {
            datetime: '1994-03-22T14:15:00+05:30',
            latitude: 19.0760,
            longitude: 72.8777
        }
    })
});

const match = await response.json();

// Response:
{
    "totalScore": 28,
    "maxScore": 36,
    "percentage": 77.8,
    "recommendation": "Good match - Marriage recommended",
    "kootas": {
        "varna": {"score": 1, "max": 1, "description": "Excellent spiritual compatibility"},
        "vashya": {"score": 2, "max": 2, "description": "Strong mutual attraction"},
        "tara": {"score": 2, "max": 3, "description": "Good birth star alignment"},
        "yoni": {"score": 3, "max": 4, "description": "Compatible physical nature"},
        "grahaMaitri": {"score": 5, "max": 5, "description": "Perfect mental harmony"},
        "gana": {"score": 5, "max": 6, "description": "Similar temperaments"},
        "bhakoot": {"score": 5, "max": 7, "description": "Good financial prospects"},
        "nadi": {"score": 5, "max": 8, "description": "Healthy progeny indicated"}
    }
}

Dosha Compatibility Check

// Check dosha compatibility between partners
const doshaResponse = await fetch('https://api.vedika.io/v2/astrology/match/dosha', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
        male: {
            datetime: '1992-08-15T06:30:00+05:30',
            latitude: 28.6139,
            longitude: 77.2090
        },
        female: {
            datetime: '1994-03-22T14:15:00+05:30',
            latitude: 19.0760,
            longitude: 72.8777
        }
    })
});

const doshaMatch = await doshaResponse.json();

// Response:
{
    "mangalDosha": {
        "maleHas": true,
        "femaleHas": true,
        "compatible": true,
        "note": "Both partners have Mangal Dosha - cancellation effect"
    },
    "nadiDosha": {
        "present": false,
        "type": null,
        "severity": null
    },
    "bhakootDosha": {
        "present": false
    },
    "overallCompatibility": "safe",
    "recommendations": []
}

AI-Enhanced Matching

Vedika's AI goes beyond traditional matching with natural language analysis:

// AI-powered compatibility analysis
const aiResponse = await fetch('https://api.vedika.io/api/v1/astrology/query', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
        question: "Analyze the marriage compatibility between these two people. What are the strengths and challenges of this match?",
        birthDetails: {
            datetime: '1992-08-15T06:30:00+05:30',
            latitude: 28.6139,
            longitude: 77.2090
        },
        partnerDetails: {
            datetime: '1994-03-22T14:15:00+05:30',
            latitude: 19.0760,
            longitude: 72.8777
        }
    })
});

const analysis = await aiResponse.json();
// Returns detailed natural language analysis of compatibility

Integration for Matrimonial Sites

// Backend integration for matrimonial platform
class MatrimonyMatchService {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.baseUrl = 'https://api.vedika.io/v2/astrology';
    }

    async getCompatibilityScore(profileA, profileB) {
        // Get basic Guna matching
        const gunaMatch = await this.fetchMatch('/match/kundli', profileA, profileB);

        // Get dosha compatibility
        const doshaMatch = await this.fetchMatch('/match/dosha', profileA, profileB);

        // Calculate composite score
        const compositeScore = this.calculateComposite(gunaMatch, doshaMatch);

        return {
            gunaScore: gunaMatch.totalScore,
            gunaPercentage: gunaMatch.percentage,
            doshaCompatible: doshaMatch.overallCompatibility === 'safe',
            compositeScore,
            badge: this.getMatchBadge(compositeScore),
            kootaDetails: gunaMatch.kootas
        };
    }

    getMatchBadge(score) {
        if (score >= 80) return 'Excellent Match';
        if (score >= 60) return 'Good Match';
        if (score >= 40) return 'Average Match';
        return 'Requires Consultation';
    }
}

Display Matching Results

// React component for match display
function MatchResultCard({ match }) {
    return (
        

            

                {match.gunaScore}/36
                {match.gunaPercentage}%
            

            
{match.badge}

            

                {Object.entries(match.kootaDetails).map(([koota, data]) => (
                    

                        {koota}
                        

                            

                        
                        {data.score}/{data.max}
                    
                ))}
            

            {!match.doshaCompatible && (
                

                    Dosha considerations present - consult astrologer
                
            )}
        
    );
}