Kundali Matching API: Build Compatibility Features in 30 Minutes

Kundali matching (guna milan) is the most-used feature on matrimonial platforms. This tutorial shows you how to integrate the full 36-point compatibility score, rajju-vedha dosha check, and aggregate recommendation into any app in 30 minutes.

The matching endpoints

Fetching guna milan + rajju-vedha + aggregate

const BASE = 'https://vedintelastroapi.com/api/v1'

async function getCompatibility(male: BirthData, female: BirthData) {
  const params = new URLSearchParams({
    api_key: process.env.VEDINTEL_KEY!,
    // Male birth data
    m_dob: male.dob, m_tob: male.tob,
    m_lat: String(male.lat), m_lon: String(male.lon), m_tz: String(male.tz),
    // Female birth data
    f_dob: female.dob, f_tob: female.tob,
    f_lat: String(female.lat), f_lon: String(female.lon), f_tz: String(female.tz),
  })

  const [northMatch, rajjuVedha, aggregate] = await Promise.all([
    fetch(`${BASE}/matching/north-match?${params}`).then(r => r.json()),
    fetch(`${BASE}/matching/rajju-vedha-match?${params}`).then(r => r.json()),
    fetch(`${BASE}/matching/aggregate-match?${params}`).then(r => r.json()),
  ])

  return {
    gunaMilan: northMatch.response,   // 36-point Ashta Koota breakdown
    rajjuVedha: rajjuVedha.response, // Rajju + Vedha dosha check
    aggregate: aggregate.response,    // Overall recommendation
  }
}

Response structure

// gunaMilan response (north-match)
{
  "total_points": 28,
  "maximum_points": 36,
  "compatibility_percentage": 77.8,
  "koota": [
    { "name": "Varna", "points": 1, "max": 1, "description": "Spiritual compatibility" },
    { "name": "Vashya", "points": 2, "max": 2, "description": "Dominance compatibility" },
    { "name": "Tara", "points": 3, "max": 3, "description": "Birth star compatibility" },
    { "name": "Yoni", "points": 3, "max": 4, "description": "Biological compatibility" },
    { "name": "Maitri", "points": 5, "max": 5, "description": "Mental compatibility" },
    { "name": "Gana", "points": 6, "max": 6, "description": "Temperament match" },
    { "name": "Bhakoot", "points": 7, "max": 7, "description": "Destiny compatibility" },
    { "name": "Nadi", "points": 1, "max": 8, "description": "Genetic compatibility" }
  ],
  "recommendation": "Good match — 18+ points required, 28 points indicates strong compatibility."
}

Displaying the results

Recommended UI pattern:

1. Score banner — "28 / 36 points (77%)" in large type at the top
2. Koota breakdown — expandable list of all 8 kootas with points and descriptions
3. Dosha flags — colour-coded Rajju and Vedha pass/fail badges
4. Recommendation text — from the aggregate endpoint

South Indian matching

Replace /matching/north-match with /matching/south-match for the 10-point Dasha Koota system used in Tamil Nadu, Karnataka, and Kerala. The request parameters are identical.

Bulk matching for matrimony platforms

The /matching/bulk-north-match endpoint accepts up to 10 male-female pairs in a single POST request. Ideal for showing compatibility scores against a list of suggested profiles.