How to Integrate Kundali Matching in Your App via API

Why Kundali Matching is a Must-Have Feature

Kundali matching (gun milan) is the #1 feature request for astrology and matrimonial apps in India and among the Indian diaspora. With 85% of Indian marriages still being arranged or semi-arranged, compatibility matching drives user engagement and premium conversions. Apps with kundali matching see 3.5x higher retention rates.

Understanding Ashtakoot System

The Ashtakoot (8 kutas) system evaluates compatibility across 8 dimensions based on Moon's nakshatra position in both birth charts. Here's the complete breakdown:

API Integration - Basic Implementation

Let's implement kundali matching step by step. We'll use Vedika API which handles all complex calculations and dosha detection.

Step 1: Initialize API Client

import requests
from typing import Dict

class KundaliMatchingAPI:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.vedika.io"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    def match_kundali(self, groom: Dict, bride: Dict) -> Dict:
        """Perform kundali (Ashtakoot Guna Milan) matching.

        groom and bride are birth details:
        {"datetime": ..., "latitude": ..., "longitude": ..., "timezone": ...}
        """
        response = requests.post(
            f"{self.base_url}/v2/astrology/guna-milan",
            headers=self.headers,
            json={"male": groom, "female": bride}
        )
        response.raise_for_status()
        return response.json()["data"]

    def mangal_dosha(self, birth: Dict) -> Dict:
        """Mangal (Manglik) dosha check for one person"""
        response = requests.post(
            f"{self.base_url}/v2/astrology/mangal-dosha",
            headers=self.headers,
            json=birth
        )
        response.raise_for_status()
        return response.json()["data"]

# Initialize
api = KundaliMatchingAPI("your_api_key_here")

Step 2: Collect Birth Details for Both Partners

# Bride's birth details (geocode the birth place to latitude/longitude in your app)
bride = {
    "datetime": "1995-03-15T08:30:00",
    "latitude": 19.0760,      # Mumbai
    "longitude": 72.8777,
    "timezone": "+05:30"
}

# Groom's birth details
groom = {
    "datetime": "1992-07-22T14:45:00",
    "latitude": 28.6139,      # Delhi
    "longitude": 77.2090,
    "timezone": "+05:30"
}

Step 3: Perform Matching

# Match kundalis
match_result = api.match_kundali(groom=groom, bride=bride)

# Display results
print(f"\n{'='*50}")
print(f"Compatibility Score: {match_result['total_points']}/{match_result['maximum_points']}")
print(f"Compatibility: {match_result['match_result']}")
print(f"{'='*50}\n")

# Individual koota scores
for koota in match_result['guna_kootas']:
    status = "✓" if koota['points'] == koota['maximum_points'] else "○"
    print(f"{status} {koota['name']:15} {koota['points']}/{koota['maximum_points']}")

# Nadi dosha: both partners in the same Nadi score 0 of 8 on the Nadi koota
nadi = match_result['gunaDetails']['nadi']
print(f"\nNadi: {nadi['score']}/{nadi['maxPoints']}")
print(f"Nadi Dosha: {'present' if nadi['score'] == 0 else 'not present'}")

API Response Structure

A trimmed example response from POST /v2/astrology/guna-milan (the full data object also carries per-koota descriptions and tips; the Python class above returns just data):

{
  "success": true,
  "data": {
    "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,
        "male_koot": "Vaishya",
        "female_koot": "Kshatriya"
      },
      {
        "name": "Vasya",
        "points": 2.0,
        "maximum_points": 2,
        "male_koot": "Capricorn",
        "female_koot": "Aries"
      },
      {
        "name": "Tara",
        "points": 3.0,
        "maximum_points": 3,
        "male_koot": "Atimitra",
        "female_koot": "Sampat"
      },
      {
        "name": "Yoni",
        "points": 2.0,
        "maximum_points": 4,
        "male_koot": "Mongoose",
        "female_koot": "Elephant"
      },
      {
        "name": "Graha Maitri",
        "points": 1.0,
        "maximum_points": 5,
        "male_koot": "Saturn",
        "female_koot": "Mars"
      },
      {
        "name": "Gana",
        "points": 6.0,
        "maximum_points": 6,
        "male_koot": "Manav",
        "female_koot": "Manav"
      },
      {
        "name": "Bhakoot",
        "points": 7.0,
        "maximum_points": 7,
        "male_koot": "Capricorn",
        "female_koot": "Aries"
      },
      {
        "name": "Nadi",
        "points": 8.0,
        "maximum_points": 8,
        "male_koot": "Antya",
        "female_koot": "Madhya"
      }
    ],
    "gunaDetails": {
      "nadi": {
        "name": "Nadi (Health & Genetic Compatibility)",
        "score": 8.0,
        "maxPoints": 8,
        "interpretation": "Different Nadis - excellent health compatibility and genetic diversity."
      }
    },
    "interpretation": {
      "summary": "A very good match with strong overall compatibility.",
      "strengths": [
        "Good mutual attraction and influence",
        "Favorable birth star harmony"
      ],
      "challenges": [
        "Different spiritual temperaments"
      ]
    },
    "male_info": {
      "moon_nakshatra": "Uttara Ashadha",
      "moon_sign": "Capricorn"
    },
    "female_info": {
      "moon_nakshatra": "Bharani",
      "moon_sign": "Aries"
    }
  },
  "billing": {
    "charged": 0.05,
    "currency": "USD"
  }
}

Advanced: Mangal Dosha Detection

Mangal dosha (Kuja dosha) is critical for marriage matching. Here's how to detect and analyze it:

# One call per partner (reuses the api client from Step 1)
bride_dosha = api.mangal_dosha(bride)
groom_dosha = api.mangal_dosha(groom)

# Dosha matching logic
def is_mangal_dosha_compatible(dosha1, dosha2):
    """Check if Mangal doshas cancel out"""

    # Both have dosha - cancels out
    if dosha1['has_dosha'] and dosha2['has_dosha']:
        return True, "Both partners have Mangal dosha - cancels out"

    # Neither has dosha
    if not dosha1['has_dosha'] and not dosha2['has_dosha']:
        return True, "No Mangal dosha in either chart"

    # One has dosha
    dosha = dosha1 if dosha1['has_dosha'] else dosha2

    # Cancellation rules already applied by the API
    if dosha['is_cancelled']:
        return True, "Dosha cancelled by an exception rule"

    if dosha['severity'] == 'Mild':
        return True, "Mild dosha - acceptable"

    return False, "Unmatched Mangal dosha - requires remedies"

compatible, reason = is_mangal_dosha_compatible(bride_dosha, groom_dosha)
print(f"Mangal Dosha Compatible: {compatible}")
print(f"Reason: {reason}")

Building a Complete Matching Feature

Frontend Implementation (React)

import React, { useState } from 'react';
import axios from 'axios';

function KundaliMatchingForm() {
  // Each holds birth details: { datetime, latitude, longitude, timezone }
  const [bride, setBride] = useState({});
  const [groom, setGroom] = useState({});
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

  const handleMatch = async () => {
    setLoading(true);

    try {
      // Your own backend route calls POST https://api.vedika.io/v2/astrology/guna-milan
      // with { male: groom, female: bride } and returns the "data" object,
      // so the API key never reaches the browser.
      const matchResult = await axios.post('/api/kundali/match', { groom, bride });

      setResult(matchResult.data);
    } catch (error) {
      console.error('Matching failed:', error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div className="max-w-4xl mx-auto p-6">
      <h2 className="text-3xl font-bold mb-8">Kundali Matching</h2>

      <div className="grid md:grid-cols-2 gap-8 mb-8">
        {/* Bride Details */}
        <div className="bg-white rounded-lg shadow p-6">
          <h3 className="text-xl font-bold mb-4 text-pink-600">Bride Details</h3>
          <BirthDetailsForm
            data={bride}
            onChange={setBride}
          />
        </div>

        {/* Groom Details */}
        <div className="bg-white rounded-lg shadow p-6">
          <h3 className="text-xl font-bold mb-4 text-blue-600">Groom Details</h3>
          <BirthDetailsForm
            data={groom}
            onChange={setGroom}
          />
        </div>
      </div>

      <button
        onClick={handleMatch}
        disabled={loading}
        className="w-full bg-purple-600 text-white py-3 rounded-lg font-bold"
      >
        {loading ? 'Matching...' : 'Match Kundalis'}
      </button>

      {result && <MatchingResults result={result} />}
    </div>
  );
}

function MatchingResults({ result }) {
  const getScoreColor = (score) => {
    if (score >= 33) return 'text-green-600';
    if (score >= 25) return 'text-blue-600';
    if (score >= 18) return 'text-orange-600';
    return 'text-red-600';
  };

  return (
    <div className="mt-8 space-y-6">
      {/* Overall Score */}
      <div className="bg-gradient-to-r from-purple-100 to-pink-100 rounded-xl p-8 text-center">
        <div className={`text-6xl font-bold mb-2 ${getScoreColor(result.total_points)}`}>
          {result.total_points}/{result.maximum_points}
        </div>
        <div className="text-xl font-semibold">{result.match_result}</div>
        <div className="text-gray-700 mt-2">{result.recommendation}</div>
      </div>

      {/* Kuta Breakdown */}
      <div className="bg-white rounded-xl shadow p-6">
        <h3 className="text-xl font-bold mb-4">Detailed Analysis</h3>
        <div className="space-y-3">
          {result.guna_kootas.map((koota, idx) => (
            <div key={idx} className="flex items-center justify-between border-b pb-3">
              <div className="flex-1">
                <div className="font-bold">{koota.name}</div>
                <div className="text-sm text-gray-600">{koota.description}</div>
              </div>
              <div className="text-right">
                <div className="text-2xl font-bold">
                  {koota.points}/{koota.maximum_points}
                </div>
              </div>
            </div>
          ))}
        </div>
      </div>

      {/* Doshas: Nadi dosha shows as 0 of 8 on the Nadi koota */}
      {result.gunaDetails.nadi.score === 0 && (
        <div className="bg-red-50 rounded-xl p-6">
          <h3 className="text-xl font-bold mb-4 text-red-900">Doshas Detected</h3>
          <div className="space-y-4">
            <div>
              <div className="font-bold text-red-800">Nadi Dosha</div>
              <div className="text-sm text-red-700">
                {result.gunaDetails.nadi.interpretation}
              </div>
            </div>
          </div>
        </div>
      )}

      {/* Summary */}
      <div className="bg-blue-50 rounded-xl p-6">
        <h3 className="text-xl font-bold mb-4">Analysis</h3>
        <p className="text-gray-700">{result.interpretation.summary}</p>
      </div>
    </div>
  );
}

Batch Matching for Matrimonial Platforms

For matrimonial sites, you need to match one profile against hundreds. Here's an efficient batch implementation:

from concurrent.futures import ThreadPoolExecutor
from typing import Dict, List

def find_compatible_matches(
    base_profile: Dict,
    candidates: List[Dict],
    min_score: int = 18
) -> List[Dict]:
    """Find all compatible matches from a list of candidates.

    base_profile is the groom's birth details; each candidate is
    {"id": ..., "birth": {datetime, latitude, longitude, timezone}} for a bride.
    """

    # One Guna Milan call per candidate, run in parallel
    with ThreadPoolExecutor(max_workers=8) as pool:
        results = list(pool.map(
            lambda c: api.match_kundali(base_profile, c['birth']),
            candidates
        ))

    # Filter and sort results
    compatible = [
        {
            'profileId': candidates[i]['id'],
            'score': result['total_points'],
            'compatibility': result['match_result'],
            'concerns': result['interpretation']['challenges']
        }
        for i, result in enumerate(results)
        if result['total_points'] >= min_score
    ]

    # Sort by score descending
    compatible.sort(key=lambda x: x['score'], reverse=True)

    return compatible

# Find top matches
user_birth = groom
all_candidates = get_all_eligible_profiles()  # Your DB query: [{"id": ..., "birth": {...}}, ...]

matches = find_compatible_matches(
    user_birth,
    all_candidates,
    min_score=24  # Only "Good" or better
)

# Display top 10 matches
for match in matches[:10]:
    print(f"{match['score']}/36 - {match['compatibility']}")

Caching Strategy for Performance

import hashlib
import json
import redis
from datetime import timedelta
from typing import Dict, Optional

redis_client = redis.Redis(host='localhost', port=6379, decode_responses=True)

def match_cache_key(groom: Dict, bride: Dict) -> str:
    """Deterministic key: the same two sets of birth details always map to the same key"""
    raw = json.dumps([groom, bride], sort_keys=True)
    return f"match:{hashlib.sha256(raw.encode()).hexdigest()}"

def get_cached_match(groom: Dict, bride: Dict) -> Optional[Dict]:
    """Check cache for existing match result"""
    cached = redis_client.get(match_cache_key(groom, bride))
    if cached:
        return json.loads(cached)
    return None

def cache_match_result(groom: Dict, bride: Dict, result: Dict):
    """Cache match result for 30 days"""
    redis_client.setex(
        match_cache_key(groom, bride),
        timedelta(days=30),
        json.dumps(result)
    )

def match_with_cache(groom: Dict, bride: Dict) -> Dict:
    """Match with caching"""
    # Check cache first
    cached = get_cached_match(groom, bride)
    if cached:
        return cached

    # Calculate new match
    result = api.match_kundali(groom, bride)

    # Cache result
    cache_match_result(groom, bride, result)

    return result

Monetization Strategies

Best Practices

Frequently Asked Questions