Kundali API for Developers 2026: Build Birth Chart Apps with Real Calculations

Kundali (also spelled kundli) is the Vedic astrological birth chart — a map of the sky at the exact moment of birth, calculated for a specific geographic location. For developers, it is a structured dataset: planetary longitudes converted to sidereal coordinates, mapped to 12 houses, annotated with dignity, nakshatra, dasha period, and active combinations. Every consumer-facing astrology app in India — from matrimonial platforms to daily horoscope apps — is built on top of this data.

This guide walks through what a kundali actually contains at the data level, why ephemeris accuracy matters, how to use Vedika's kundali endpoints, and how to build a matrimonial matching feature end-to-end. All code examples are production-ready.

1. What Is a Kundali — Technical Explanation

A kundali encodes three things: where the planets were in the sky at the moment of birth, which zodiac sign was rising on the eastern horizon (the ascendant or Lagna), and how those positions map to 12 life domains (houses).

The Vedic system works in the sidereal (star-fixed) zodiac, not the tropical (Sun-fixed) zodiac used in Western astrology. The two zodiacs diverge by approximately 23.85 degrees (the Lahiri ayanamsa value in 2026). When a Western calculation says the Sun is at 15 degrees Aries, the same position in the Vedic sidereal system is approximately 22 degrees Pisces.

The 12 houses are assigned based on the ascendant sign. In the Whole Sign system (the default in Vedic astrology), the ascendant sign becomes the first house in its entirety. The second house is the next sign, the third the sign after that, and so on around the wheel. A planet's house is determined by which sign it occupies, not by degree boundaries.

2. Key Data Points in a Kundali

A complete kundali API response should contain the following data categories. Each one is independently useful and can power separate features in your application.

3. Why Swiss Ephemeris Matters for Accuracy

Swiss Ephemeris (swisseph) is the astronomical library developed by Astrodienst in Switzerland. It is the same ephemeris used by professional astrology software including Solar Fire, Jyotish Studio, and Jagannatha Hora. It is accurate to sub-arcsecond precision for dates between 2000 BCE and 3000 CE.

The alternative is using pre-computed table lookups or simplified polynomial approximations. These can introduce errors of 0.1 to 0.5 degrees — enough to misplace a planet in the wrong nakshatra pada or, in edge cases, the wrong sign entirely. For a matrimonial platform making marriage compatibility decisions, that error matters.

Vedika runs Swiss Ephemeris in-house on its Cloud Run infrastructure. Every planetary calculation runs against the actual ephemeris files — not a cached table, not a third-party calculation service. The Lahiri ayanamsa is applied using the ICRC standard value anchored to J2000.0 (23.853222 degrees at the epoch), which produces the correct ~23.85 degree correction for 2026 dates.

4. Vedika's Kundali Endpoints

Vedika exposes three primary kundali-related endpoints under the /v2/astrology/ path.

Generate a Full Kundali

// Generate complete Vedic kundali
const response = await fetch('https://api.vedika.io/v2/astrology/kundli', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'vk_live_your_key_here'
  },
  body: JSON.stringify({
    datetime: '1992-11-22T08:45:00',  // ISO 8601, local time
    latitude: 28.6139,                 // Delhi
    longitude: 77.2090,
    timezone: '+05:30'                 // UTC offset, NOT IANA name
  })
});

const kundali = await response.json();

// Sample response structure:
// {
//   planets: [
//     {
//       name: "Sun",
//       sign: "Scorpio",
//       house: 4,
//       degree: 6.34,
//       dignity: "Neutral",
//       isRetrograde: false,
//       isCombust: false,
//       nakshatra: "Anuradha",
//       nakshatraPada: 1,
//       nakshatraLord: "Saturn",
//       nakshatraDeity: "Mitra"
//     },
//     // ... all 9 planets
//   ],
//   ascendant: { sign: "Leo", degree: 14.22 },
//   houses: [ { house: 1, sign: "Leo", lord: "Sun", lordHouse: 4 }, ... ],
//   activeYogas: ["Gaja Kesari Yoga", "Budha-Aditya Yoga"],
//   doshas: { mangalDosha: false, kaalSarpDosha: false },
//   dasha: {
//     mahadasha: "Jupiter",
//     antardasha: "Saturn",
//     pratyantar: "Mercury",
//     dashaEndDate: "2028-05-14"
//   },
//   navamsa: [ /* D9 planetary positions */ ],
//   dasamsa: [ /* D10 planetary positions */ ]
// }

Python Example: Full Kundali

import requests

def get_kundali(datetime_str, lat, lng, tz, api_key):
    """Fetch complete Vedic kundali from Vedika API."""
    response = requests.post(
        'https://api.vedika.io/v2/astrology/kundli',
        headers={
            'Content-Type': 'application/json',
            'x-api-key': api_key
        },
        json={
            'datetime': datetime_str,
            'latitude': lat,
            'longitude': lng,
            'timezone': tz
        },
        timeout=15
    )
    response.raise_for_status()
    return response.json()

# Usage
chart = get_kundali(
    datetime_str='1992-11-22T08:45:00',
    lat=28.6139,
    lng=77.2090,
    tz='+05:30',
    api_key='vk_live_your_key_here'
)

# Access planet positions
for planet in chart['planets']:
    print(f"{planet['name']}: {planet['sign']} (House {planet['house']}) — {planet['nakshatra']}")

5. Detecting Mangal Dosha

Mangal Dosha (Kuja Dosha) is one of the most commonly checked conditions in Indian matrimonial astrology. Per Brihat Parashara Hora Shastra Chapter 77, Mangal Dosha is present when Mars (Mangal) is placed in house 1, 2, 4, 7, 8, or 12 of the natal chart. The 2nd house is included in the standard BPHS definition — this is a point of variation across different software tools, and Vedika follows the full 6-house BPHS definition.

The dosha has cancellation conditions (Neecha Bhanga, Mars in its own sign, certain house combinations). Vedika checks these automatically and returns the final verdict including the cancellation reason if applicable.

Check Mangal Dosha Directly

// Dedicated Mangal Dosha check
const response = await fetch('https://api.vedika.io/v2/astrology/mangal-dosha', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'vk_live_your_key_here'
  },
  body: JSON.stringify({
    datetime: '1992-11-22T08:45:00',
    latitude: 28.6139,
    longitude: 77.2090,
    timezone: '+05:30'
  })
});

const dosha = await response.json();

// Response:
// {
//   mangalDosha: true,
//   marsHouse: 7,
//   isCancelled: false,
//   cancellationReason: null,
//   doshaStrength: "High",
//   affectedHouses: [7],
//   recommendation: "Partner should also have Mangal Dosha for compatibility"
// }

// Or for a cancelled dosha:
// {
//   mangalDosha: true,
//   marsHouse: 2,
//   isCancelled: true,
//   cancellationReason: "Mars in own sign (Scorpio) — dosha neutralised per BPHS",
//   doshaStrength: "None (cancelled)"
// }

6. Building a Matrimonial Matching Feature

Guna Milan (Ashtakoot Milan) is the standard Vedic compatibility system used by matrimonial platforms across India. It evaluates 8 compatibility categories (Koot) between two birth charts, with each category weighted by a maximum point value. The total is 36 points.

Standard thresholds: below 18 points is typically rejected in traditional practice, 18-24 is acceptable, 24-32 is good, 32+ is considered excellent.

Guna Milan API Call

// Guna Milan: 36-point compatibility matching
const response = await fetch('https://api.vedika.io/v2/astrology/guna-milan', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'vk_live_your_key_here'
  },
  body: JSON.stringify({
    // Person 1 (typically bride)
    person1: {
      datetime: '1994-03-15T06:30:00',
      latitude: 19.0760,
      longitude: 72.8777,
      timezone: '+05:30'
    },
    // Person 2 (typically groom)
    person2: {
      datetime: '1991-08-22T11:15:00',
      latitude: 12.9716,
      longitude: 77.5946,
      timezone: '+05:30'
    }
  })
});

const matching = await response.json();

// Response structure:
// {
//   totalScore: 28,
//   maxScore: 36,
//   percentage: 77.8,
//   verdict: "Good match",
//   breakdown: {
//     varna:      { score: 1, max: 1 },
//     vashya:     { score: 2, max: 2 },
//     tara:       { score: 2, max: 3 },
//     yoni:       { score: 3, max: 4 },
//     grahaMaitri:{ score: 4, max: 5 },
//     gana:       { score: 6, max: 6 },
//     bhakut:     { score: 7, max: 7 },
//     nadi:       { score: 3, max: 8 }
//   },
//   doshaWarnings: {
//     person1MangalDosha: false,
//     person2MangalDosha: true,
//     doshaCompatibility: "Mismatch — one partner has Mangal Dosha, the other does not"
//   },
//   person1Nakshatra: "Rohini",
//   person2Nakshatra: "Hasta"
// }

Complete Matrimonial Matching Workflow

// Full matrimonial compatibility check
async function checkCompatibility(bride, groom, apiKey) {
  const headers = {
    'Content-Type': 'application/json',
    'x-api-key': apiKey
  };

  // Run Guna Milan and individual kundalis in parallel
  const [gunaResult, brideChart, groomChart] = await Promise.all([
    fetch('https://api.vedika.io/v2/astrology/guna-milan', {
      method: 'POST', headers,
      body: JSON.stringify({ person1: bride, person2: groom })
    }).then(r => r.json()),

    fetch('https://api.vedika.io/v2/astrology/kundli', {
      method: 'POST', headers,
      body: JSON.stringify(bride)
    }).then(r => r.json()),

    fetch('https://api.vedika.io/v2/astrology/kundli', {
      method: 'POST', headers,
      body: JSON.stringify(groom)
    }).then(r => r.json())
  ]);

  return {
    compatibility: {
      score: gunaResult.totalScore,
      percentage: gunaResult.percentage,
      verdict: gunaResult.verdict,
      breakdown: gunaResult.breakdown
    },
    doshaCheck: {
      brideMangalDosha: brideChart.doshas.mangalDosha,
      groomMangalDosha: groomChart.doshas.mangalDosha,
      mismatch: brideChart.doshas.mangalDosha !== groomChart.doshas.mangalDosha
    },
    brideNakshatra: gunaResult.person1Nakshatra,
    groomNakshatra: gunaResult.person2Nakshatra,
    brideDasha: brideChart.dasha,
    groomDasha: groomChart.dasha
  };
}

// Example usage
const result = await checkCompatibility(
  { datetime: '1994-03-15T06:30:00', latitude: 19.0760, longitude: 72.8777, timezone: '+05:30' },
  { datetime: '1991-08-22T11:15:00', latitude: 12.9716, longitude: 77.5946, timezone: '+05:30' },
  'vk_live_your_key_here'
);

if (result.compatibility.score >= 24) {
  console.log(`Good match: ${result.compatibility.score}/36 (${result.compatibility.percentage}%)`);
} else {
  console.log(`Below threshold: ${result.compatibility.score}/36`);
}

if (result.doshaCheck.mismatch) {
  console.warn('Mangal Dosha mismatch — flag for pandit review');
}

7. Performance: Response Times and Caching Strategies

Kundali calculations are computationally deterministic. The same birth datetime and coordinates always produce the same chart. This is one of the few API categories where aggressive caching is safe and strongly recommended.

Typical Response Times

Caching Implementation

// Redis-based kundali caching
const redis = require('redis');
const client = redis.createClient();

// Cache key: deterministic from birth data only
function kundaliCacheKey(birthData) {
  const { datetime, latitude, longitude, timezone } = birthData;
  // Round coordinates to 4 decimal places (~11m accuracy)
  const lat = parseFloat(latitude).toFixed(4);
  const lng = parseFloat(longitude).toFixed(4);
  return `kundli:v1:${datetime}:${lat}:${lng}:${timezone}`;
}

async function getKundaliCached(birthData, apiKey) {
  const cacheKey = kundaliCacheKey(birthData);

  // Check cache first
  const cached = await client.get(cacheKey);
  if (cached) {
    return { data: JSON.parse(cached), fromCache: true };
  }

  // Fetch from API
  const response = await fetch('https://api.vedika.io/v2/astrology/kundli', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
    body: JSON.stringify(birthData)
  });

  const data = await response.json();

  // Cache for 30 days (birth charts never change)
  await client.setEx(cacheKey, 60 * 60 * 24 * 30, JSON.stringify(data));

  return { data, fromCache: false };
}

// Guna Milan caching (keyed on both birth datasets)
function gunaMillanCacheKey(person1, person2) {
  const k1 = kundaliCacheKey(person1);
  const k2 = kundaliCacheKey(person2);
  // Ensure consistent ordering regardless of which is passed first
  const keys = [k1, k2].sort();
  return `guna:v1:${keys[0]}:${keys[1]}`;
}

8. Pricing for Kundali-Focused Applications

Vedika uses a wallet-credit model. Your subscription funds a credit wallet; each API call deducts credits at a per-endpoint rate. This model is well-suited for kundali apps because the call volume is predictable and caching makes the effective cost per user very low.

With proper caching (birth chart cached per user on first generation), a Starter plan at $12/month can support a surprisingly large number of active users — the bottleneck becomes new user registrations rather than existing user activity.

Frequently Asked Questions