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));

Related APIs