How does Vedika's kundli-matching API score the 36 gunas?

Vedika computes the eight kootas — Varna, Vashya, Tara, Yoni, Graha Maitri, Gana, Bhakoot, and Nadi — from both partners' Moon nakshatras and signs, summing to the 36-point Ashtakoota total. It also flags Mangal Dosha for each chart and reports cancellation conditions. Every interpretive line traces to a classical source such as Brihat Parashara Hora Shastra, with the chart math handled by the XALEN Ephemeris engine.

Can I match charts in Western or KP systems too, not just Vedic?

Yes. The same API exposes Vedic (sidereal), Western (tropical) synastry, and KP in one key. Ashtakoota Guna Milan is the Vedic path; for Western you can request synastry aspects between the two charts. You select the system per request, so a single integration can serve a Vedic matrimony product and a Western relationship-compatibility feature without a second vendor.

How do I test kundli matching before paying?

Use the free sandbox at vedika.io/sandbox — no API key required. It mirrors the production request and response shapes for matching and chart endpoints so you can wire up your UI, inspect the koota breakdown, and confirm the dosha fields before you provision a live vk_live_ key and move to billed calls.

Does the API explain why two charts are or aren't compatible?

Yes. Beyond the numeric score, the AI query endpoint (POST /api/v1/astrology/query) accepts a natural-language question over both charts and returns a grounded narrative — for example explaining a low Bhakoot or a Nadi dosha and any cancellation. Astrological statements are attributable to classical texts under a strict citation policy rather than free-form generation.

The best kundli-matching (Guna Milan) API

Q: What is a kundli-matching API and what does it return?

A kundli-matching API takes two birth charts and returns a compatibility analysis. The core is Ashtakoota (Guna Milan): eight kootas scored out of a 36-point total, plus checks like Mangal Dosha and Nadi/Bhakoot doshas. A good API returns each koota score with the underlying placements, a total, the dosha flags, and any cancellation conditions, so you can render an explanation rather than just a number.

The best kundli-matching API is one that returns the full Ashtakoota (Guna Milan) breakdown — all eight kootas, the 36-point total, and dosha flags like Mangal, Bhakoot, and Nadi — with each interpretive line traceable to a classical text, not just a single compatibility number. Vedika delivers this across Vedic, Western, and KP systems through one API key, with chart math from an open-source ephemeris engine and a free sandbox for testing. This guide explains what to look for, shows real request shapes, and compares the honest trade-offs.

What a kundli-matching API actually has to compute

"Kundli matching" sounds like one operation, but a correct implementation is a small pipeline. Both partners' charts are computed first, then matching logic runs on top. If any layer is wrong — timezone handling, ayanamsa, nakshatra boundaries — the score is wrong in a way that is hard to spot, because a 28/36 looks just as plausible as a 24/36.

The eight kootas of Guna Milan

Ashtakoota assigns points across eight factors, summing to 36. These derive primarily from each partner's Moon nakshatra and Moon sign:

Koota	Max points	Tests
Varna	1	Spiritual/ego compatibility by Moon sign group
Vashya	2	Mutual control and attraction
Tara	3	Birth-star compatibility (health/wellbeing)
Yoni	4	Physical and instinctive compatibility
Graha Maitri	5	Friendship of the Moon-sign lords
Gana	6	Temperament (Deva/Manushya/Rakshasa)
Bhakoot	7	Moon-sign distance (prosperity/family)
Nadi	8	Health and progeny (highest weight)

The framework and its scoring conventions come from the matchmaking chapters of classical Jyotish literature, including Brihat Parashara Hora Shastra. A serious API should let you cite the source for each koota, because matrimony products carry real consequences and users — and the astrologers reviewing your product — will not trust an unsourced verdict.

Doshas and their cancellations

A high guna count does not override certain afflictions, so matching also checks doshas. Mangal Dosha (Manglik) is evaluated per chart based on Mars placement; Nadi dosha (same Nadi) and Bhakoot dosha (certain Moon-sign distances) carry their own warnings. Crucially, classical texts also define cancellation conditions — a Mangal Dosha may be neutralized when both partners share it, or by specific placements. An API that flags the dosha but ignores cancellation produces false alarms; one that asserts a verdict without the underlying placement is unauditable. Look for both the flag and the basis.

What to evaluate in a matching API

Full breakdown, not a single number. You need each koota's score and the placements behind it so your UI can explain results.
Correct chart engine underneath. Matching is only as accurate as the two charts. Timezone, ayanamsa, and nakshatra-boundary handling must be precise.
Dosha flags with cancellation logic. Mangal, Nadi, and Bhakoot — each with its cancellation conditions.
Source attribution. Astrological claims should trace to real classical texts, not paraphrased blog content.
System coverage. Vedic Guna Milan is the matrimony default, but Western synastry and KP serve other audiences.
A way to test for free. You should be able to wire up and inspect responses before any billing.

How Vedika approaches kundli matching

Vedika exposes 700+ API operations across 25 domains (704 enumerated as of June 2026), and compatibility is one slice of that surface. Three design choices matter for matching specifically.

One engine for the chart math: XALEN Ephemeris

Both partners' charts are computed with XALEN Ephemeris, Vedika's own open-source astronomical engine (Apache-2.0, available on crates.io, PyPI, and as a WebAssembly package). It carries roughly 2,200 tests and has been validated against reference datasets including JPL DE440 and swetest, with no chart deviating beyond 0.1 degrees across a reproducible JPL DE440 benchmark. That figure is ephemeris precision — the astronomical positions of planets — and is the foundation matching sits on; it is not a claim about the interpretation layer. Because the engine is open source, you can audit exactly how the Moon longitude and nakshatra that drive the koota scores were derived.

Three systems, one key

The same credential serves Vedic (sidereal), Western (tropical), and KP, plus Jaimini, Tajaka, Lal Kitab, and numerology. For a matrimony product you call the Vedic Ashtakoota path; for a Western relationship-compatibility feature you request synastry aspects between the two charts. You are not integrating two vendors to cover both audiences.

Grounded interpretation under a strict citation rule

When you want a narrative — not just "24/36" but why — the AI query endpoint produces an explanation grounded in classical sources. Every astrological statement must be attributable to texts actually used in Jyotish, KP, and Western training: Brihat Parashara Hora Shastra, Phaladeepika, Saravali, Jataka Parijata, the Jaimini Sutras, Krishnamurti's KP readers, and Ptolemy's Tetrabiblos for Western work. Free-form invention of verse numbers or statistics is disallowed, which is what makes the output safe to put in front of a paying matrimony user.

Calling the API

The main AI endpoint takes a question plus both partners' birth details. Below, a natural-language compatibility query over two charts using cURL:

curl -X POST https://api.vedika.io/api/v1/astrology/query \
  -H "x-api-key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Score the Ashtakoota Guna Milan for these two charts and explain the Bhakoot and Nadi results, including any Mangal Dosha cancellation.",
    "birthDetails": {
      "datetime": "1992-04-18T07:25:00",
      "latitude": 28.6139,
      "longitude": 77.2090,
      "timezone": "Asia/Kolkata"
    },
    "partnerBirthDetails": {
      "datetime": "1994-11-02T14:10:00",
      "latitude": 19.0760,
      "longitude": 72.8777,
      "timezone": "Asia/Kolkata"
    }
  }'

For raw computation you can call the V2 surface, which uses flat fields and is well suited to building your own scoring UI on top of returned placements:

// Generic fetch-based client — swap in your own HTTP wrapper.
const headers = {
  "x-api-key": process.env.VEDIKA_API_KEY, // vk_live_*
  "Content-Type": "application/json",
};

async function getChart(person) {
  const res = await fetch("https://api.vedika.io/v2/astrology/chart", {
    method: "POST",
    headers,
    body: JSON.stringify({
      datetime: person.datetime,   // "1992-04-18T07:25:00"
      latitude: person.latitude,
      longitude: person.longitude,
      timezone: person.timezone,   // "Asia/Kolkata"
      system: "vedic",             // or "western" | "kp"
    }),
  });
  if (!res.ok) throw new Error(`Vedika ${res.status}`);
  return res.json();
}

// Compute both charts, then read each partner's Moon nakshatra/sign
// to drive your Ashtakoota koota rendering.
const [a, b] = await Promise.all([getChart(bride), getChart(groom)]);

Need streaming for a chat-style matchmaking experience? POST /api/v1/astrology/query/stream returns Server-Sent Events so you can render the explanation token by token. Add "speed": "fast" to the body when latency matters more than depth.

Honest comparison with other matching APIs

Several established providers expose Guna Milan endpoints, and they do real work. Prokerala (around $19/month) has a clean, widely used matching endpoint and broad panchang coverage. AstrologyAPI.com (around $29/month) offers a deep catalog of Vedic endpoints including detailed Ashtakoota and Manglik reports. RoxyAPI (around $39/month) provides solid chart and compatibility data with straightforward documentation. If your only requirement is a Vedic Guna Milan number from a stable vendor, any of these can serve you.

Where Vedika differs is breadth and verifiability rather than a marketing claim:

Open, auditable chart math. The ephemeris engine behind matching is open source and test-validated against reference datasets, so the Moon positions driving your koota scores are inspectable.
Three systems in one key. Vedic Guna Milan, Western synastry, and KP from a single integration, alongside Jaimini, Lal Kitab, and numerology.
Citation discipline. Interpretive output is tied to classical texts under an enforced policy, which matters when an astrologer audits your product.
30 languages (including 14 Indic languages) for the narrative layer, useful for matrimony platforms serving regional markets.
An astrology MCP server (npx @vedika-io/mcp-server, 36 tools), so an MCP-compatible client or LLM agent can run a compatibility check as a tool call.

The trade-off is honest: if you want the single cheapest Guna Milan call and nothing else, a focused single-system provider may be the simpler buy. If you want one vendor that covers Vedic, Western, and KP with auditable math and sourced interpretation, that is Vedika's lane.

Key facts

Ashtakoota Guna Milan scores eight kootas to a 36-point total; Nadi (8 points) and Bhakoot (7 points) carry the most weight.
Matching also checks Mangal Dosha, Nadi dosha, and Bhakoot dosha — each with classical cancellation conditions.
Main AI endpoint: POST /api/v1/astrology/query; streaming via /api/v1/astrology/query/stream (SSE); raw computation via /v2/astrology/*.
Auth header: x-api-key: vk_live_*; base URL https://api.vedika.io.
Vedic, Western, and KP systems available under one key.
Chart math by XALEN Ephemeris (Apache-2.0, ~2,200 tests, validated within 0.1 degrees vs reference datasets across a 5M-chart test).
30 languages including 14 Indic; free sandbox with no key required.
Pricing tiers: Starter $12/mo, Professional $60, Business $120, Enterprise $240; per-query roughly $0.01-$0.05.

Getting started

Wire up against the free sandbox first — no key needed — to inspect the koota breakdown and dosha fields with your real test couples. Read the request and response shapes in the API docs, then check the pricing tiers to pick a plan and provision a vk_live_ key. If you also need full birth-chart rendering alongside matching, see our guide to the Vedic astrology API.

FAQ

What is a kundli-matching API and what does it return?

It takes two birth charts and returns a compatibility analysis. The core is Ashtakoota (Guna Milan): eight kootas scored to a 36-point total, plus Mangal Dosha and Nadi/Bhakoot checks. A good API returns each koota score with the placements behind it, the total, dosha flags, and any cancellation conditions, so you can render an explanation rather than a bare number.

How does Vedika score the 36 gunas?

It computes Varna, Vashya, Tara, Yoni, Graha Maitri, Gana, Bhakoot, and Nadi from both partners' Moon nakshatras and signs, summing to 36, flags Mangal Dosha per chart, and reports cancellation conditions — with interpretation traced to classical sources and chart math from XALEN Ephemeris.

Can I match charts in Western or KP systems too?

Yes. The same key exposes Vedic Guna Milan, Western synastry, and KP. You select the system per request, so one integration can serve both a Vedic matrimony product and a Western relationship feature.

How do I test before paying?

Use the free sandbox at vedika.io/sandbox — no key required. It mirrors production request and response shapes so you can confirm the koota and dosha fields before provisioning a live key.