Kundli Matching API
Horoscope compatibility for marriage
POST
/v2/astrology/kundli-matching
$0.050/call
Basic Usage
import { VedikaClient } from '@vedika-io/sdk';
const client = new VedikaClient({ apiKey: process.env.VEDIKA_API_KEY });
// Male partner's details first, female partner's second
const match = await client.getCompatibilityV2(
'kundli-matching',
{
datetime: '1992-07-15T06:00:00', // groom
latitude: 19.0760,
longitude: 72.8777,
timezone: '+05:30'
},
{
datetime: '1995-03-20T14:30:00', // bride
latitude: 28.6139,
longitude: 77.2090,
timezone: '+05:30'
}
);
console.log('Total Score:', match.total_points); // out of 36
console.log('Percentage:', match.percentage);
console.log('Verdict:', match.match_result); // e.g. 'Compatible'
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
female |
BirthDetails | Yes | Female partner's (bride's) birth details (datetime, latitude, longitude, timezone) |
male |
BirthDetails | Yes | Male partner's (groom's) birth details (datetime, latitude, longitude, timezone) |
system |
string | No | 'ashtakoot' (N. India), 'porutham' (S. India) |
includeRemedies |
boolean | No | Include remedies for low-scoring areas |
Response Structure
// What the client returns: the "data" object of POST /v2/astrology/kundli-matching
// (the SDK removes the { success, data } wrapper). Raw HTTP callers read the same
// fields under body.data. Values below are one example pair.
{
"total_points": 27,
"maximum_points": 36,
"percentage": 75,
"match_result": "Compatible",
"recommendation": "Very good match - Strong compatibility",
"guna_kootas": [
{
"id": 1,
"name": "Varna",
"male_koot": "Kshatriya",
"female_koot": "Kshatriya",
"points": 1,
"maximum_points": 1,
"description": "Kshatriya (male) vs Kshatriya (female)"
},
{
"id": 4,
"name": "Yoni",
"male_koot": "Mongoose",
"female_koot": "Elephant",
"points": 2,
"maximum_points": 4,
"description": "Mongoose vs Elephant - Neutral"
}
// ... Vasya, Tara, Graha Maitri, Gana, Bhakoot, Nadi (8 kootas in total)
],
// The same scores keyed by koota
"gunaDetails": {
"varna": { "name": "Varna (Spiritual Compatibility)", "score": 1, "maxPoints": 1 },
"nadi": { "name": "Nadi (Health & Genetic Compatibility)", "score": 8, "maxPoints": 8 }
// ... vasya, tara, yoni, grahaMaitri, gana, bhakoot
},
"male_info": { "moon_sign": "Sagittarius", "moon_nakshatra": "Uttara Ashadha" },
"female_info": { "moon_sign": "Aries", "moon_nakshatra": "Bharani" },
"interpretation": {
"summary": "A very good match with strong overall compatibility.",
"marriageProspects": "Very favorable for marriage. Minor adjustments may be needed but the foundation is strong.",
"strengths": ["Strong spiritual compatibility", "..."],
"challenges": ["Bhakoot Dosha may affect finances/family"],
"guidance": ["This is a good match with strong potential", "..."]
},
"remedies": ["Bhakoot Dosha: Perform Bhakoot Dosha Shanti"]
}
Ashtakoot Gunas Explained
| Guna | Points | Evaluates |
|---|---|---|
| Varna | 1 | Spiritual and ego compatibility |
| Vashya | 2 | Power dynamics and mutual attraction |
| Tara | 3 | Health and well-being after marriage |
| Yoni | 4 | Sexual and physical compatibility |
| Graha Maitri | 5 | Mental wavelength and friendship |
| Gana | 6 | Temperament and behavior |
| Bhakoot | 7 | Love, family happiness, finances |
| Nadi | 8 | Health of progeny, genetic compatibility |
Scoring Guide:
- 18+ points: Minimum recommended for marriage
- 25+ points: Good compatibility
- 32+ points: Excellent match
South Indian (Porutham) System
// Use the Nakshatra Porutham system (10 poruthams)
const match = await client.getCompatibilityV2(
'nakshatra-porutham',
groomDetails, // male partner first
brideDetails
);
// The result lists the 10 poruthams and how many matched
// (field names are in the API reference for POST /v2/astrology/nakshatra-porutham)
console.log(match);
Manglik Compatibility Check
// Standalone Manglik check
const brideDosha = await client.getDoshasV2('mangal-dosha', {
datetime: '1995-03-20T14:30:00',
latitude: 28.6139,
longitude: 77.2090,
timezone: '+05:30'
});
const groomDosha = await client.getDoshasV2('mangal-dosha', {
datetime: '1992-07-15T06:00:00',
latitude: 19.0760,
longitude: 72.8777,
timezone: '+05:30'
});
// Check compatibility
if (brideDosha.has_dosha && !groomDosha.has_dosha) {
console.log('Manglik mismatch - check for cancellations');
console.log('Cancelled:', brideDosha.is_cancelled);
console.log('Cancellation factors:', brideDosha.cancellation_reasons);
}
Complete Matching Report
async function generateMatchingReport(bride, groom) {
const client = new VedikaClient({ apiKey: process.env.VEDIKA_API_KEY });
// Get complete matching analysis (male partner first, female second)
const [match, brideDosha, groomDosha] = await Promise.all([
client.getCompatibilityV2('kundli-matching', groom, bride),
client.getDoshasV2('mangal-dosha', bride),
client.getDoshasV2('mangal-dosha', groom)
]);
// Build comprehensive report
const report = {
summary: {
score: `${match.total_points}/${match.maximum_points}`,
percentage: `${match.percentage}%`,
verdict: match.match_result
},
gunaBreakdown: match.guna_kootas.map(g => ({
guna: g.name,
score: `${g.points}/${g.maximum_points}`,
status: g.points === g.maximum_points ? 'Matched' : 'Not Matched'
})),
concerns: match.guna_kootas
.filter(g => g.points < g.maximum_points)
.map(g => `${g.name}: ${g.description}`),
manglikAnalysis: {
brideStatus: brideDosha.has_dosha ? 'Manglik' : 'Non-Manglik',
groomStatus: groomDosha.has_dosha ? 'Manglik' : 'Non-Manglik',
compatible: brideDosha.has_dosha === groomDosha.has_dosha
},
recommendation: match.total_points >= 25
? 'This match is recommended for marriage'
: 'Consult an astrologer for detailed analysis',
remedies: match.remedies
};
return report;
}
// Usage
const report = await generateMatchingReport(
{ datetime: '1995-03-20T14:30:00', latitude: 28.6139, longitude: 77.2090, timezone: '+05:30' },
{ datetime: '1992-07-15T06:00:00', latitude: 19.0760, longitude: 72.8777, timezone: '+05:30' }
);
console.log(JSON.stringify(report, null, 2));