Building a Kundli Matching Feature Using Vedic Astrology API

About the author: Brajesh Vashisht is a Vedic Astrologer and KP Systems Specialist with 22 years of experience in Vedic astrology and Krishnamurti Paddhati. He holds a postgraduate degree in Jyotish Shastra from Banaras Hindu University and has authored two books on KP sub-lord theory and nakshatra analysis.

Kundli matching (Gun Milan) is the most critical feature for any Indian matrimonial platform. Families rely on the Ashtakoot system to evaluate compatibility across 8 dimensions, from spiritual alignment to health and progeny. Getting this wrong, whether through inaccurate calculations or missing dosha checks, means lost trust from users who take these assessments seriously before making life decisions.

The RoxyAPI Vedic Astrology API returns the full 36-point Ashtakoot breakdown, active doshas, dosha cancellations, and a human-readable recommendation in a single API call. This guide shows you how to integrate Kundli matching, Manglik dosha detection, and Kalsarpa dosha analysis into your matrimonial application using the TypeScript SDK. All calculations are verified against 828 gold standard test cases from authoritative Jyotish sources including DrikPanchang and onlinejyotish.

How the Ashtakoot Gun Milan system works

The Ashtakoot (eight-factor) system evaluates compatibility between two birth charts across these 8 kootas:

The total maximum score is 36 points. Scores above 18 (50%) are generally considered compatible for marriage. Nadi carries the highest weight at 8 points because it evaluates health and progeny potential, which is considered the most consequential factor in Vedic matchmaking. When Nadi scores zero (both persons share the same Nadi type), this is called Nadi dosha and is traditionally considered a serious incompatibility.

Compatibility interpretation by score range:

• 28 to 36 points (78% or higher): Excellent match, highly recommended
• 21 to 27 points (58% to 75%): Very good match, union recommended
• 18 to 20 points (50% to 56%): Average match, proceed with awareness of challenges
• Below 18 points: Below average, consult an experienced astrologer before proceeding

Ready to build this? RoxyAPI Vedic Astrology API gives you Gun Milan, Manglik dosha, Kalsarpa dosha, and 40+ more endpoints with one API key. See pricing.

How to calculate Gun Milan compatibility with the SDK

Install the SDK and call the compatibility endpoint with birth data for both persons:

npm install @roxyapi/sdk

import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data, error } = await roxy.vedicAstrology.calculateGunMilan({
  body: {
    person1: {
      date: '1990-07-15',
      time: '14:30:00',
      latitude: 28.6139,
      longitude: 77.209,
      timezone: 5.5,
    },
    person2: {
      date: '1992-03-20',
      time: '10:00:00',
      latitude: 19.076,
      longitude: 72.8777,
      timezone: 5.5,
    },
  },
});

if (data) {
  console.log(`Score: ${data.total}/${data.maxScore} (${data.percentage}%)`);
  console.log('Compatible:', data.isCompatible);
  console.log('Recommendation:', data.recommendation);

  // Display each koota score
  for (const koota of data.breakdown) {
    console.log(`  ${koota.category}: ${koota.score}/${koota.maxScore} (${koota.person1} vs ${koota.person2})`);
  }

  // Check for active doshas in the match
  if (data.doshas.length > 0) {
    console.log('Active doshas:', data.doshas.join(', '));
  }

  // Show dosha cancellations with reasons
  for (const cancel of data.doshaCancellations) {
    console.log(`  ${cancel.dosha} cancelled: ${cancel.reason}`);
  }
}

The SDK method roxy.vedicAstrology.calculateGunMilan() accepts birth data for both persons and returns a fully typed response. No manual TypeScript interfaces or raw fetch calls needed.

How the Gun Milan API response is structured

Here is a real response from the compatibility endpoint:

{
  "total": 24.5,
  "maxScore": 36,
  "percentage": 68.06,
  "isCompatible": true,
  "recommendation": "Union is recommended",
  "doshas": [],
  "doshaCancellations": [],
  "breakdown": [
    {
      "category": "Varna",
      "score": 1,
      "maxScore": 1,
      "person1": "Brahmin",
      "person2": "Kshatriya",
      "description": "Spiritual compatibility and mutual respect"
    },
    {
      "category": "Nadi",
      "score": 8,
      "maxScore": 8,
      "person1": "Madhya",
      "person2": "Antya",
      "description": "Health and progeny"
    }
  ]
}

Each entry in the breakdown array includes the category name, score, maxScore, classifications for both persons (person1 and person2), and a description of what that koota evaluates. For example, a Yoni entry might show person1: "Cow" and person2: "Tiger" with the corresponding compatibility score based on the classical Yoni animal pairing table.

The top-level doshas array lists any active doshas detected in the match (such as Nadi dosha when both persons share the same Nadi). The doshaCancellations array provides reasons when a dosha is technically present but cancelled by other chart factors. This is critical for matrimonial platforms because many users will see a zero Nadi score and panic. Showing the cancellation reason (when applicable) reduces unnecessary anxiety and support tickets.

For a complete match report, call Gun Milan for the overall score, then call Manglik and Kalsarpa dosha endpoints for each person individually. All three calls can run in parallel since they are independent.

How to check Manglik dosha for each person

Manglik dosha (Mars affliction) is one of the most important pre-marriage checks. The dedicated endpoint returns severity, effects across multiple life areas, classical exceptions, and remedies:

const { data } = await roxy.vedicAstrology.checkManglikDosha({
  body: {
    date: '1990-07-15',
    time: '14:30:00',
    latitude: 28.6139,
    longitude: 77.209,
    timezone: 5.5,
  },
});

if (data) {
  console.log('Manglik:', data.present);
  if (data.present) {
    console.log('Severity:', data.severity);  // "Mild", "Moderate", or "Severe"
    console.log('Description:', data.description);

    // Effects on different life areas
    if (data.effects) {
      console.log('Marriage impact:', data.effects.marriage);
      console.log('Personality:', data.effects.personality);
      console.log('Timing:', data.effects.timing);
    }

    // Classical cancellation exceptions
    if (data.exceptions) {
      console.log('Exceptions:', data.exceptions);
    }

    // Traditional remedies
    if (data.remedies) {
      console.log('Remedies:', data.remedies);
    }
  }
}

The key matchmaking rule for Manglik dosha: if both persons are Manglik, the dosha is neutralized and the match proceeds normally. If only one person has it, the severity level ("Mild", "Moderate", or "Severe") and the available remedies help determine next steps for the couple and their families. The effects.timing field notes that Manglik dosha intensity typically reduces after age 28, which is relevant for matrimonial platforms serving younger users.

How to check Kalsarpa dosha

Kalsarpa dosha occurs when all planets are hemmed between the Rahu-Ketu axis. The endpoint identifies which of the 12 classical types is present:

const { data } = await roxy.vedicAstrology.checkKalsarpaDosha({
  body: {
    date: '1990-07-15',
    time: '14:30:00',
    latitude: 28.6139,
    longitude: 77.209,
    timezone: 5.5,
  },
});

if (data && data.present) {
  console.log('Type:', data.type);        // e.g., "Ananta", "Takshak", "Padma"
  console.log('Severity:', data.severity);
  console.log('Description:', data.description);

  if (data.effects) {
    console.log('Career impact:', data.effects.career);
    console.log('Health:', data.effects.health);
    console.log('Positive aspects:', data.effects.positive);
  }
}

The 12 Kalsarpa types (Ananta, Kulik, Vasuki, Shankhapala, Padma, Mahapadma, Takshak, Karkotak, Shankhachud, Ghatak, Vishdhar, Sheshnag) each carry different implications depending on the Rahu-Ketu axis and house positions. The effects.positive field is unique to RoxyAPI: it highlights potential spiritual growth benefits, which is valuable context for users who may be alarmed by a dosha diagnosis. The effects.duration field notes when the dosha is most active within the Vimshottari dasha system, helping users understand the timeline of effects rather than treating it as a permanent condition.

How to test the endpoints with curl

# Gun Milan compatibility
curl -X POST https://roxyapi.com/api/v2/vedic-astrology/compatibility \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "person1": {"date":"1990-07-15","time":"14:30:00","latitude":28.6139,"longitude":77.209,"timezone":5.5},
    "person2": {"date":"1992-03-20","time":"10:00:00","latitude":19.076,"longitude":72.8777,"timezone":5.5}
  }'

# Manglik dosha check
curl -X POST https://roxyapi.com/api/v2/vedic-astrology/manglik \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"date":"1990-07-15","time":"14:30:00","latitude":28.6139,"longitude":77.209,"timezone":5.5}'

# Kalsarpa dosha check
curl -X POST https://roxyapi.com/api/v2/vedic-astrology/kalsarpa \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"date":"1990-07-15","time":"14:30:00","latitude":28.6139,"longitude":77.209,"timezone":5.5}'

Replace YOUR_API_KEY with your RoxyAPI key. Test all endpoints live in the Vedic Astrology API reference.

Frequently Asked Questions

Q: What is the minimum Gun Milan score for a compatible match? A: Traditionally, 18 out of 36 points (50%) is the threshold. The API returns an isCompatible boolean based on this threshold and a recommendation string with guidance. Scores above 28 are considered excellent, while scores below 18 suggest consulting an experienced astrologer.

Q: How does the API handle Nadi dosha? A: Nadi dosha (both persons sharing the same Nadi) is the most critical incompatibility factor. When detected, it appears in the doshas array. If classical cancellation conditions are met (such as both persons sharing the same rashi), the cancellation and its reason appear in doshaCancellations.

Q: Can I run Gun Milan and dosha checks in a single API call? A: Gun Milan and dosha checks are separate endpoints, but you can call them in parallel. The Gun Milan response includes a doshas array for match-level doshas. Individual Manglik and Kalsarpa checks provide detailed severity, effects, and remedies for each person separately.

Q: What birth data does each endpoint require? A: All endpoints accept the same five fields: date (YYYY-MM-DD), time (HH:MM:SS, 24-hour), latitude, longitude, and timezone (UTC offset, defaults to 5.5 for IST). The compatibility endpoint wraps these in person1 and person2 objects.

Q: Does the API support Sadhesati (Saturn transit) analysis for marriage timing? A: Yes. Use roxy.vedicAstrology.checkSadhesati() to check if either person is in a Sadhesati period, which is traditionally considered unfavorable for marriage. The endpoint returns the current phase, Saturn position, and expected duration.

Q: How accurate are the dosha calculations? A: All calculations use sidereal positions with Lahiri ayanamsa, verified against NASA JPL Horizons data. Manglik dosha checks Mars placement in all relevant houses (1st, 2nd, 4th, 7th, 8th, 12th from both Lagna and Moon) and evaluates classical cancellation conditions. The test suite includes 828 gold standard test cases cross-referenced against DrikPanchang and onlinejyotish.

Conclusion

Kundli matching for matrimonial applications requires accurate Ashtakoot scoring, dosha detection, and clear compatibility recommendations that users can understand and trust. The RoxyAPI Vedic Astrology API provides all three through dedicated endpoints with structured, interpreted responses. The Gun Milan endpoint handles the 36-point calculation and dosha detection in one call, while separate Manglik and Kalsarpa endpoints provide detailed per-person analysis with severity levels, effects, and remedies. The TypeScript SDK eliminates manual type definitions and HTTP boilerplate, letting you focus on building the user experience your matrimonial platform needs.

Start building your Kundli matching feature at RoxyAPI Vedic Astrology API or explore the full Vedic Astrology API reference. Check pricing for plan details.