RoxyAPI

Menu

Build a Kundli Matching Feature in 50 Lines of Code

8 min read
•By Rahul Sharma
vedic-astrologyKundli MatchingGun MilanAshtakootaAPI Tutorial

Ship Ashtakoota kundli matching with Manglik analysis in your app using 50 lines of code. Complete guide with API integration, score display, and compatibility interpretation.

Build a Kundli Matching Feature in 50 Lines of Code

Kundli matching (gun milan) is the most searched Vedic astrology feature in India. Every major matrimonial platform offers it. Every astrology app needs it. And with the right API, you can ship a production-ready kundli matching feature in under 50 lines of code.

The Ashtakoota system scores compatibility across 8 factors totaling 36 points. Add Manglik Dosha analysis and you have a feature that covers what users and families expect when evaluating marriage compatibility.

This guide shows you how to build it. No astrology knowledge required.

What Kundli Matching Actually Calculates

The Ashtakoota (8-Factor) System

Ashtakoota means "eight groups." Each group (koota) evaluates a different compatibility dimension:

Koota Points What It Evaluates
Varna 1 Spiritual compatibility, ego levels
Vashya 2 Mutual attraction, dominance dynamics
Tara 3 Destiny compatibility, health of union
Yoni 4 Physical and sexual compatibility
Graha Maitri 5 Mental compatibility, friendship
Gana 6 Temperament compatibility
Bhakoot 7 Love, family harmony, financial prosperity
Nadi 8 Health of progeny, genetic compatibility
Total 36 Overall compatibility

Score Interpretation

Score Range Interpretation
0-17 Not recommended for marriage
18-24 Average compatibility, acceptable
25-32 Good compatibility, recommended
33-36 Excellent compatibility, highly recommended

18 out of 36 is the traditional minimum for a match to be considered viable.

Manglik Analysis

Alongside the 36-point score, kundli matching checks both charts for Manglik Dosha (Mars placement in specific houses). If one person is Manglik and the other is not, it raises a traditional compatibility concern (though cancellation conditions often apply).

The Code: 50 Lines

Here is the complete feature. Frontend form, API call, result display:

// kundli-match.ts - Complete kundli matching feature
import { astrology } from './services/astrology';

interface MatchInput {
  person1: { date: string; time: string; lat: number; lng: number; name: string };
  person2: { date: string; time: string; lat: number; lng: number; name: string };
}

export async function getKundliMatch(input: MatchInput) {
  const response = await fetch('https://api.roxyapi.com/api/v2/vedic-astrology/match', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.ROXYAPI_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      person1: {
        date: input.person1.date,
        time: input.person1.time,
        latitude: input.person1.lat,
        longitude: input.person1.lng,
      },
      person2: {
        date: input.person2.date,
        time: input.person2.time,
        latitude: input.person2.lat,
        longitude: input.person2.lng,
      },
    }),
  });

  return response.json();
}

export function interpretScore(score: number): string {
  if (score >= 33) return 'Excellent match. Highly recommended for marriage.';
  if (score >= 25) return 'Good compatibility. Marriage is recommended.';
  if (score >= 18) return 'Average compatibility. Marriage is acceptable with awareness of weaker areas.';
  return 'Below minimum threshold. Detailed analysis recommended before proceeding.';
}

export function formatResult(data: any) {
  return {
    totalScore: `${data.total_score}/36`,
    interpretation: interpretScore(data.total_score),
    kootas: data.kootas,
    manglik: {
      person1: data.person1_manglik,
      person2: data.person2_manglik,
      compatible: data.manglik_compatible,
    },
  };
}

That is the core logic. 50 lines. API handles all the Vedic calculations. You handle the user experience.

Building the Full Feature

Input Form

The matching form needs birth details for both people:

<form id="kundli-match-form">
  <h3>Person 1</h3>
  <input type="text" name="name1" placeholder="Name" required />
  <input type="date" name="date1" required />
  <input type="time" name="time1" required />
  <input type="text" name="city1" placeholder="Birth city" required />

  <h3>Person 2</h3>
  <input type="text" name="name2" placeholder="Name" required />
  <input type="date" name="date2" required />
  <input type="time" name="time2" required />
  <input type="text" name="city2" placeholder="Birth city" required />

  <button type="submit">Check Compatibility</button>
</form>

City to Coordinates

Birth city needs to be converted to latitude/longitude. Use a geocoding API or a pre-built city database:

async function cityToCoords(city: string) {
  // Option 1: Geocoding API (Google, Mapbox, Nominatim)
  const response = await fetch(
    `https://nominatim.openstreetmap.org/search?q=${encodeURIComponent(city)}&format=json&limit=1`
  );
  const results = await response.json();
  return { lat: parseFloat(results[0].lat), lng: parseFloat(results[0].lon) };
}

For Indian cities specifically, maintaining a local database of major cities with coordinates is faster and more reliable than geocoding.

Result Display

The match result should display clearly:

function renderResult(result: any) {
  return `
    <div class="match-result">
      <div class="score-circle">
        <span class="score">${result.totalScore}</span>
      </div>
      <p class="interpretation">${result.interpretation}</p>

      <h3>Koota Breakdown</h3>
      <table>
        <tr><th>Koota</th><th>Score</th><th>Max</th></tr>
        ${result.kootas.map((k: any) => `
          <tr>
            <td>${k.name}</td>
            <td>${k.score}</td>
            <td>${k.max}</td>
          </tr>
        `).join('')}
      </table>

      <h3>Manglik Analysis</h3>
      <p>Person 1: ${result.manglik.person1 ? 'Manglik' : 'Non-Manglik'}</p>
      <p>Person 2: ${result.manglik.person2 ? 'Manglik' : 'Non-Manglik'}</p>
      <p>Status: ${result.manglik.compatible ? 'Compatible' : 'Requires attention'}</p>
    </div>
  `;
}

Visual Score Indicator

Users respond strongly to visual score representation. A circular gauge that fills based on the score out of 36 creates an immediate understanding:

  • Red zone (0-17): Below minimum
  • Yellow zone (18-24): Acceptable
  • Green zone (25-32): Good
  • Gold zone (33-36): Excellent

Caching Kundli Match Results

Kundli matches are highly cacheable:

Cache key: Sort the two birth data sets alphabetically so that matching Person A with Person B produces the same cache key as matching Person B with Person A.

function matchCacheKey(p1: any, p2: any): string {
  const key1 = `${p1.date}:${p1.time}:${p1.lat}:${p1.lng}`;
  const key2 = `${p2.date}:${p2.time}:${p2.lat}:${p2.lng}`;
  const sorted = [key1, key2].sort();
  return `match:${sorted[0]}:${sorted[1]}`;
}

Cache TTL: Permanent. The birth data never changes, so the match result never changes.

Monetization Strategies

Freemium Model

Free: Basic Ashtakoota score (total out of 36).

Premium: Detailed koota breakdown, Manglik analysis, remedial suggestions, Dasha compatibility, Navamsa comparison.

This is the model most Indian astrology apps use. The score is the hook. The detailed analysis is the conversion.

Per-Report Pricing

Charge per kundli matching report (INR 99-499). This works for matrimonial platforms where users pay per match analyzed. No subscription required.

API Reselling

Build a white-label kundli matching widget that other websites (matrimonial platforms, astrology blogs, pandit websites) can embed. Charge per API call or monthly subscription.

What Users Expect

Indian users have specific expectations for kundli matching features:

  1. All 8 kootas displayed individually. Not just the total score. Users (and their families) want to see where compatibility is strong and where it is weak.

  2. Manglik status for both people. This is checked separately from Ashtakoota and is the first thing many families look for.

  3. Score interpretation in clear language. Not everyone understands what 24/36 means. Provide a plain-language recommendation.

  4. Dosha cancellation details. If Manglik Dosha is present, users want to know if cancellation conditions apply.

  5. PDF report generation. Families share kundli matching reports. A downloadable PDF that can be printed and shared is a strong premium feature.

  6. Hindi language support. The majority of kundli matching users prefer Hindi or regional language interfaces. Even if your app is English-first, Hindi support for this specific feature dramatically increases adoption.

Technical Considerations

Birth Time Precision

Kundli matching depends on Moon sign (Rashi) and Nakshatra, both of which require accurate birth time. A birth time error of 15+ minutes can change the Moon's nakshatra, which directly affects the Ashtakoota score.

Best practice: Show a note explaining why accurate birth time matters. Offer a "birth time unknown" option that uses approximate calculations with a disclaimer.

Multiple Ayanamsa Support

Vedic astrology uses different ayanamsa (the offset between tropical and sidereal zodiac). Lahiri is the most common in India. Krishnamurti (KP) is used by KP practitioners. Some users specifically require one or the other.

The RoxyAPI Vedic Astrology API supports multiple ayanamsa options so your kundli matching feature can serve both mainstream and KP astrology users.

Frequently Asked Questions

Q: How accurate is API-based kundli matching compared to a traditional astrologer? A: The Ashtakoota calculation is mathematical. Given the same birth data and ayanamsa, an API and a traditional astrologer produce the same 36-point score. The difference is in interpretation nuance: a human astrologer adds contextual judgment from the full chart. For the standard matching score and Manglik check, API-based matching is equivalent in accuracy.

Q: Do I need to understand Vedic astrology to build this feature? A: No. The API handles all calculations. You need to understand the input format (birth date, time, location) and the output format (scores, kootas, Manglik status). The API documentation explains every field in the response.

Q: Can I offer this feature for free? A: Yes, with caching. A permanent cache means each unique match is only calculated once. Even with thousands of daily users, the actual API calls are manageable. RoxyAPI Starter plan at $39/month (5,000 requests) supports thousands of cached matches.

Q: What other Vedic features should I add alongside kundli matching? A: The natural expansion path: individual kundli (birth chart) display, Dasha period calculation, Manglik Dosha detailed analysis, Panchang (daily Hindu calendar), and transit predictions. RoxyAPI provides all these endpoints under the same API key.

Q: How do I handle the case where both people have the same birth details? A: Identical birth details produce a perfect 36/36 match (you are matching someone with themselves). In practice, this almost never happens because birth times are rarely identical to the minute. If it does occur, display the result normally. It is mathematically correct.

Q: Is kundli matching only relevant for the Indian market? A: Primarily, yes. Kundli matching is deeply embedded in Indian marriage culture. However, the Indian diaspora worldwide (US, UK, Canada, Middle East, Southeast Asia) also uses kundli matching, making it relevant for any app serving the Indian community globally.

Start building kundli matching features. Check the RoxyAPI Vedic Astrology API, browse the API documentation, or view pricing.