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 male = {
    datetime: '1992-08-15T06:30:00',
    latitude: 28.6139,
    longitude: 77.2090,
    timezone: '+05:30'
};
const female = {
    datetime: '1994-03-22T14:15:00',
    latitude: 19.0760,
    longitude: 72.8777,
    timezone: '+05:30'
};

const response = await fetch('https://api.vedika.io/v2/astrology/guna-milan', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({ male, female })
});

const match = await response.json();   // { success, data, billing }

// match.data (trimmed example; the values depend on the two charts):
// {
//     "total_points": 29.0,
//     "maximum_points": 36,
//     "percentage": 81,
//     "match_result": "Compatible",
//     "recommendation": "Very good match - Strong compatibility",
//     "guna_kootas": [
//         {"name": "Varna", "points": 0.0, "maximum_points": 1},
//         {"name": "Vasya", "points": 2.0, "maximum_points": 2},
//         {"name": "Tara", "points": 3.0, "maximum_points": 3},
//         {"name": "Yoni", "points": 2.0, "maximum_points": 4},
//         {"name": "Graha Maitri", "points": 1.0, "maximum_points": 5},
//         {"name": "Gana", "points": 6.0, "maximum_points": 6},
//         {"name": "Bhakoot", "points": 7.0, "maximum_points": 7},
//         {"name": "Nadi", "points": 8.0, "maximum_points": 8}
//     ],
//     "gunaDetails": { "nadi": { "score": 8.0, "maxPoints": 8, "interpretation": "..." }, ... },
//     "interpretation": { "summary": "...", "strengths": [...], "challenges": [...] }
// }

Dosha Compatibility Check

Mangal, Kaal Sarp and Pitru dosha are checked per person, so call the dosha endpoint once for each partner. Nadi dosha is a couple-level check and already sits in the Guna Milan response above: the Nadi koota scores 0 of 8 when both partners share a Nadi.

// Check dosha compatibility between partners (male and female as defined above)
const doshaFor = async (person) => {
    const res = await fetch('https://api.vedika.io/v2/astrology/all-doshas', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer YOUR_API_KEY'
        },
        body: JSON.stringify(person)
    });
    return (await res.json()).data;
};

const [maleDoshas, femaleDoshas] = await Promise.all([doshaFor(male), doshaFor(female)]);

// Each result holds the Mangal, Kaal Sarp and Pitru dosha findings for one person.
// Print them to see every field. If both partners have Mangal dosha, it traditionally cancels out.
console.log(JSON.stringify({ maleDoshas, femaleDoshas }, null, 2));

// Nadi dosha comes from the Guna Milan response
const nadi = match.data.gunaDetails.nadi;
console.log(nadi.score === 0 ? 'Nadi dosha present' : 'No Nadi dosha');

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',
        'Authorization': 'Bearer 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: male,
        partnerBirthDetails: female
    })
});

const analysis = await aiResponse.json();
console.log(analysis.response); // 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';
    }

    async post(path, body) {
        const response = await fetch(`${this.baseUrl}${path}`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${this.apiKey}`
            },
            body: JSON.stringify(body)
        });
        if (!response.ok) throw new Error(`Vedika API error: ${response.status}`);
        return (await response.json()).data;
    }

    // profileA is the male partner, profileB the female partner:
    // { datetime, latitude, longitude, timezone }
    async getCompatibilityScore(profileA, profileB) {
        // Get basic Guna matching
        const gunaMatch = await this.post('/v2/astrology/guna-milan', {
            male: profileA,
            female: profileB
        });

        // Get Mangal dosha for each partner
        const [mangalA, mangalB] = await Promise.all([
            this.post('/v2/astrology/mangal-dosha', profileA),
            this.post('/v2/astrology/mangal-dosha', profileB)
        ]);

        // Mangal dosha is fine when neither partner has it (or it is cancelled),
        // or when both have it; Nadi dosha shows as 0 on the Nadi koota
        const active = (d) => d.has_dosha && !d.is_cancelled;
        const doshaCompatible =
            active(mangalA) === active(mangalB) && gunaMatch.gunaDetails.nadi.score > 0;

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

        return {
            gunaScore: gunaMatch.total_points,
            gunaPercentage: gunaMatch.percentage,
            doshaCompatible,
            compositeScore,
            badge: this.getMatchBadge(compositeScore),
            kootaDetails: gunaMatch.guna_kootas
        };
    }

    // Example weighting: the Guna Milan percentage, minus 15 points when a dosha is unmatched
    calculateComposite(gunaMatch, doshaCompatible) {
        return doshaCompatible ? gunaMatch.percentage : Math.max(0, gunaMatch.percentage - 15);
    }

    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 (
        <div className="match-card">
            <div className="score-circle">
                <span className="score">{match.gunaScore}/36</span>
                <span className="percentage">{match.gunaPercentage}%</span>
            </div>

            <div className="badge">{match.badge}</div>

            <div className="kootas">
                {match.kootaDetails.map((koota) => (
                    <div key={koota.name} className="koota-item">
                        <span>{koota.name}</span>
                        <div className="progress-bar">
                            <div style={{width: `${(koota.points/koota.maximum_points)*100}%`}}/>
                        </div>
                        <span>{koota.points}/{koota.maximum_points}</span>
                    </div>
                ))}
            </div>

            {!match.doshaCompatible && (
                <div className="dosha-warning">
                    Dosha considerations present - consult astrologer
                </div>
            )}
        </div>
    );
}