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, Optional

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

    def create_chart(self, name: str, dob: str, tob: str,
                     place: str) -> Dict:
        """Create a birth chart"""
        response = requests.post(
            f"{self.base_url}/charts/birth",
            headers=self.headers,
            json={
                "name": name,
                "dateOfBirth": dob,
                "timeOfBirth": tob,
                "placeOfBirth": place
            }
        )
        return response.json()

    def match_kundali(self, chart1_id: str, chart2_id: str,
                      detailed: bool = True) -> Dict:
        """Perform kundali matching"""
        response = requests.post(
            f"{self.base_url}/compatibility/match",
            headers=self.headers,
            json={
                "chart1": chart1_id,
                "chart2": chart2_id,
                "method": "ashtakoot",
                "includeDetails": detailed,
                "checkMangalDosha": True,
                "checkNadiDosha": True
            }
        )
        return response.json()

# Initialize
api = KundaliMatchingAPI("your_api_key_here")

Step 2: Create Charts for Both Partners

# Bride's chart
bride_chart = api.create_chart(
    name="Priya Sharma",
    dob="1995-03-15",
    tob="08:30:00",
    place="Mumbai, India"
)

# Groom's chart
groom_chart = api.create_chart(
    name="Rahul Verma",
    dob="1992-07-22",
    tob="14:45:00",
    place="Delhi, India"
)

print(f"Bride Chart ID: {bride_chart['id']}")
print(f"Groom Chart ID: {groom_chart['id']}")

Step 3: Perform Matching

# Match kundalis
match_result = api.match_kundali(
    chart1_id=bride_chart['id'],
    chart2_id=groom_chart['id'],
    detailed=True
)

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

# Individual kuta scores
for kuta in match_result['kutas']:
    status = "✓" if kuta['scored'] == kuta['maximum'] else "○"
    print(f"{status} {kuta['name']:15} {kuta['scored']}/{kuta['maximum']}")

# Doshas
print(f"\n{'='*50}")
print("Dosha Analysis:")
print(f"{'='*50}")
print(f"Mangal Dosha (Bride): {match_result['doshas']['bride']['mangalDosha']}")
print(f"Mangal Dosha (Groom): {match_result['doshas']['groom']['mangalDosha']}")
print(f"Nadi Dosha: {match_result['doshas']['nadiDosha']}")

API Response Structure

{
  "totalScore": 28,
  "compatibility": "Good",
  "recommendation": "Compatible match with good prospects",
  "kutas": [
    {
      "name": "Varna",
      "scored": 1,
      "maximum": 1,
      "description": "Spiritual compatibility - Excellent",
      "details": "Both belong to compatible varnas"
    },
    {
      "name": "Vashya",
      "scored": 2,
      "maximum": 2,
      "description": "Mutual attraction - Perfect",
      "details": "Strong natural attraction between partners"
    },
    {
      "name": "Tara",
      "scored": 3,
      "maximum": 3,
      "description": "Birth star compatibility - Excellent",
      "details": "Favorable nakshatra combination"
    },
    {
      "name": "Yoni",
      "scored": 3,
      "maximum": 4,
      "description": "Sexual compatibility - Good",
      "details": "Compatible animal signs"
    },
    {
      "name": "Graha Maitri",
      "scored": 5,
      "maximum": 5,
      "description": "Mental compatibility - Perfect",
      "details": "Moon lords are natural friends"
    },
    {
      "name": "Gana",
      "scored": 6,
      "maximum": 6,
      "description": "Temperament - Perfect match",
      "details": "Both belong to Deva gana"
    },
    {
      "name": "Bhakoot",
      "scored": 7,
      "maximum": 7,
      "description": "Love and prosperity - Excellent",
      "details": "Favorable moon sign distance"
    },
    {
      "name": "Nadi",
      "scored": 0,
      "maximum": 8,
      "description": "Health compatibility - Critical",
      "details": "Same nadi - requires remedies"
    }
  ],
  "doshas": {
    "bride": {
      "mangalDosha": {
        "present": false,
        "severity": "none",
        "houses": []
      },
      "nadiDosha": true,
      "otherDoshas": []
    },
    "groom": {
      "mangalDosha": {
        "present": true,
        "severity": "medium",
        "houses": [1, 8],
        "cancellation": "Age over 28"
      },
      "nadiDosha": true,
      "otherDoshas": []
    },
    "nadiDosha": {
      "present": true,
      "severity": "high",
      "remedies": [
        "Perform Nadi Dosha Shanti Puja",
        "Donate to couples trying to conceive",
        "Chant Maha Mrityunjaya Mantra 108 times daily"
      ]
    }
  },
  "strengths": [
    "Excellent mental compatibility (Graha Maitri 5/5)",
    "Perfect temperament match (Gana 6/6)",
    "Strong financial prospects (Bhakoot 7/7)"
  ],
  "concerns": [
    "Nadi dosha present - affects progeny",
    "Groom has medium Mangal dosha",
    "Overall score borderline for traditional standards"
  ],
  "aiInsights": {
    "summary": "This match shows strong emotional and mental compatibility...",
    "prognosis": "Good long-term prospects with remedies for Nadi dosha",
    "keyFactors": ["Strong friendship base", "Similar life goals"]
  }
}

Advanced: Mangal Dosha Detection

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

def analyze_mangal_dosha(chart_id: str) -> Dict:
    """Detailed Mangal dosha analysis"""
    response = requests.post(
        f"{base_url}/analysis/mangal-dosha",
        headers=headers,
        json={
            "chartId": chart_id,
            "checkCancellation": True,
            "includeSeverity": True
        }
    )

    dosha = response.json()

    # Severity levels
    severity_map = {
        "none": 0,
        "low": 1,
        "medium": 2,
        "high": 3,
        "severe": 4
    }

    return {
        "present": dosha['present'],
        "severity": severity_map[dosha['severity']],
        "houses": dosha['marsHouses'],
        "cancellations": dosha['cancellationFactors'],
        "matchRequired": dosha['severity'] in ['high', 'severe']
    }

# Check both partners
bride_dosha = analyze_mangal_dosha(bride_chart['id'])
groom_dosha = analyze_mangal_dosha(groom_chart['id'])

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

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

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

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

    # Check for natural cancellations
    if 'age_over_28' in severe_dosha['cancellations']:
        return True, "Dosha cancelled by age factor"

    if severe_dosha['severity'] <= 1:  # Low severity
        return True, "Low severity 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() {
  const [bride, setBride] = useState({});
  const [groom, setGroom] = useState({});
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

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

    try {
      // Create both charts
      const brideChart = await axios.post('/api/charts', bride);
      const groomChart = await axios.post('/api/charts', groom);

      // Perform matching
      const matchResult = await axios.post('/api/compatibility/match', {
        chart1: brideChart.data.id,
        chart2: groomChart.data.id
      });

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

  return (
    

      
Kundali Matching

      

        {/* Bride Details */}
        

          
Bride Details
          
        

        {/* Groom Details */}
        

          
Groom Details
          
        
      

      
        {loading ? 'Matching...' : 'Match Kundalis'}
      

      {result && }
    
  );
}

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 (
    

      {/* Overall Score */}
      

        

          {result.totalScore}/36
        
        
{result.compatibility}
        
{result.recommendation}
      

      {/* Kuta Breakdown */}
      

        
Detailed Analysis
        

          {result.kutas.map((kuta, idx) => (
            

              

                
{kuta.name}
                
{kuta.description}
              
              

                

                  {kuta.scored}/{kuta.maximum}
                
              
            
          ))}
        
      

      {/* Doshas */}
      {(result.doshas.nadiDosha || result.doshas.bride.mangalDosha.present ||
        result.doshas.groom.mangalDosha.present) && (
        

          
Doshas Detected
          

            {result.doshas.nadiDosha && (
              

                
Nadi Dosha
                

                  {result.doshas.nadiDosha.remedies?.join(', ')}
                
              
            )}
          
        
      )}

      {/* AI Insights */}
      

        
AI Analysis
        
{result.aiInsights.summary}
      
    
  );
}

Batch Matching for Matrimonial Platforms

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

async def find_compatible_matches(
    base_chart_id: str,
    candidate_chart_ids: List[str],
    min_score: int = 18
) -> List[Dict]:
    """Find all compatible matches from a list"""

    # Batch API call for efficiency
    response = await asyncio.gather(*[
        api.match_kundali(base_chart_id, candidate_id)
        for candidate_id in candidate_chart_ids
    ])

    # Filter and sort results
    compatible = [
        {
            'chartId': candidate_chart_ids[i],
            'score': result['totalScore'],
            'compatibility': result['compatibility'],
            'concerns': result['concerns']
        }
        for i, result in enumerate(response)
        if result['totalScore'] >= min_score
    ]

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

    return compatible

# Find top matches
user_chart = "chart_abc123"
all_candidates = get_all_eligible_profiles()  # Your DB query

matches = await find_compatible_matches(
    user_chart,
    [c['chartId'] for c in 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 redis
import json
from datetime import timedelta

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

def get_cached_match(chart1_id: str, chart2_id: str) -> Optional[Dict]:
    """Check cache for existing match result"""
    # Create deterministic key (sorted to handle order)
    charts = sorted([chart1_id, chart2_id])
    cache_key = f"match:{charts[0]}:{charts[1]}"

    cached = redis_client.get(cache_key)
    if cached:
        return json.loads(cached)
    return None

def cache_match_result(chart1_id: str, chart2_id: str, result: Dict):
    """Cache match result for 30 days"""
    charts = sorted([chart1_id, chart2_id])
    cache_key = f"match:{charts[0]}:{charts[1]}"

    redis_client.setex(
        cache_key,
        timedelta(days=30),
        json.dumps(result)
    )

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

    # Calculate new match
    result = api.match_kundali(chart1_id, chart2_id)

    # Cache result
    cache_match_result(chart1_id, chart2_id, result)

    return result

Monetization Strategies

Best Practices

Frequently Asked Questions