Astrology API for matrimony and matchmaking platforms

Building a matrimony or matchmaking product means handling birth-chart matching, compatibility scoring, and auspicious-date logic at scale — and most teams don't want to maintain an ephemeris engine to do it. The Vedika astrology API exposes Vedic guna milan (Ashtakoota), Manglik (Mangal Dosha) checks, Western synastry, and KP compatibility behind a single REST contract at https://api.vedika.io, with 700+ operations across 25 domains. This guide covers the endpoints, scoring fields, and integration patterns a matrimony platform actually needs.

What matchmaking needs from an astrology API

A matrimony platform has a narrow, high-stakes set of astrological requirements. Users expect a compatibility verdict that mirrors what a family astrologer would produce — a guna milan score out of 36, a clear Manglik flag for both partners, and an explanation they can trust. The integration challenges are practical:

Two charts, one verdict. Compatibility is inherently a two-party computation. You submit both partners' birth details and receive a combined score plus per-factor breakdown.
Determinism. The same two birth records must always yield the same score. Caching, audit trails, and user trust all depend on it.
Multiple traditions. Indian users expect Ashtakoota and Manglik analysis; some segments want Nadi or Dashakoota; cross-border or diaspora users may prefer Western synastry. One API covering all three avoids stitching vendors together.
Explainability. A bare number ("18/36") converts worse than the same number with the eight koota sub-scores and a sourced interpretation.

These map cleanly onto Vedika's compatibility surface. The matching domain is part of the same 704-operation catalog (enumerated June 2026) that also exposes chart computation, dashas, transits, panchang, and reports — so a matrimony app can grow from "match score" to "full kundli report" without changing vendors.

Compatibility endpoints and scoring

Vedic guna milan (Ashtakoota)

The classical North-Indian matching system scores eight kootas — Varna, Vashya, Tara, Yoni, Graha Maitri, Gana, Bhakoot, and Nadi — for a maximum of 36 gunas. The factor weights and the rule that Nadi and Bhakoot carry the heaviest dosha follow Brihat Parashara Hora Shastra (BPHS) and are reproduced in Muhurta and matchmaking chapters of the standard Jyotish curriculum. Vedika computes each koota from both partners' Moon-sign and nakshatra placements, returns the per-koota points, the aggregate, and flags Bhakoot/Nadi dosha where present.

Manglik / Mangal Dosha

Manglik analysis checks Mars placement in the 1st, 4th, 7th, 8th, and 12th houses from the relevant reference point, and evaluates cancellation conditions. Because a false "not Manglik" verdict on a half-computed chart is a real liability, the matching path requires a genuine Mars basis for both partners before it will return a verdict — it will not silently treat a missing chart as "no dosha".

Western synastry and KP

For tropical-system users, the same API exposes inter-chart synastry: aspect grids between the two natal charts, house overlays, and composite midpoints, grounded in the aspect doctrine of Ptolemy's Tetrabiblos. KP (Krishnamurti Paddhati) compatibility uses sub-lord significators per the KP Readers. The point is that you call one base URL and pick the system per request rather than integrating three separate providers.

System	What it returns	Classical basis
Vedic Ashtakoota	8 koota points, /36 total, Bhakoot & Nadi dosha flags	BPHS, Jataka Parijata
Manglik	Per-partner Mangal Dosha flag + cancellation check	Phaladeepika, matrimony chapters
Western synastry	Aspect grid, house overlays, composite midpoints	Ptolemy, Tetrabiblos
KP compatibility	Sub-lord significators, cuspal analysis	Krishnamurti KP Readers

Authentication and the request shape

Authentication is a single header, x-api-key: vk_live_*. The conversational AI endpoint accepts a natural-language question plus a birthDetails object, which makes it convenient for matchmaking because you can ask a compatibility question directly and receive a grounded, source-cited answer. For raw computation, the /v2/astrology/* endpoints take flat birth fields.

Ask a compatibility question (AI query)

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": "How compatible are these two for marriage? Give the guna milan score and Manglik status for both.",
    "birthDetails": {
      "datetime": "1992-03-14T07:25:00",
      "latitude": 28.6139,
      "longitude": 77.2090,
      "timezone": "Asia/Kolkata"
    },
    "partnerBirthDetails": {
      "datetime": "1994-11-02T19:40:00",
      "latitude": 19.0760,
      "longitude": 72.8777,
      "timezone": "Asia/Kolkata"
    }
  }'

Server-side scoring in your backend

Most matrimony platforms run the score from a trusted backend so the API key is never exposed to the browser. Here the request is built with a generic HTTP client — no vendor SDK required:

// Node.js — score a candidate pair from your matchmaking service
async function getCompatibility(personA, personB) {
  const res = await fetch("https://api.vedika.io/api/v1/astrology/query", {
    method: "POST",
    headers: {
      "x-api-key": process.env.VEDIKA_API_KEY, // vk_live_*
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      question: "Compute the 36-guna Ashtakoota score and Manglik status for both partners.",
      birthDetails: personA,        // { datetime, latitude, longitude, timezone }
      partnerBirthDetails: personB,
    }),
  });
  if (!res.ok) throw new Error(`Vedika ${res.status}`);
  return res.json();
}

Python, with explicit timezone handling

import os, requests

def compatibility(person_a: dict, person_b: dict) -> dict:
    resp = requests.post(
        "https://api.vedika.io/api/v1/astrology/query",
        headers={"x-api-key": os.environ["VEDIKA_API_KEY"]},
        json={
            "question": "Give guna milan out of 36 and Manglik status for both.",
            "birthDetails": person_a,
            "partnerBirthDetails": person_b,
        },
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()

# Timezone must match the birth place at the birth time, not the server.
# datetime is local civil time; timezone is the IANA zone string.

Computation precision matters for compatibility

Compatibility scores are unusually sensitive to chart accuracy. Guna milan keys off the Moon's nakshatra; a Moon sitting near a nakshatra boundary can flip Yoni, Gana, or Nadi koota points if the underlying longitude is off by a fraction of a degree. That makes the ephemeris layer load-bearing, not a detail.

Vedika computes charts on the XALEN Ephemeris, its own open-source astronomical engine (Apache-2.0, available on crates.io, PyPI, and as a WebAssembly package). The engine carries roughly 2,200 tests and was validated against JPL DE440 and the reference swetest tool, with no chart deviating beyond 0.1° across a reproducible JPL DE440 benchmark. This is astronomical precision — the position of the Moon and planets — and it gives the koota and Manglik logic a reliable foundation. Astrological interpretation is a separate concern, governed by the classical-source rule below.

Determinism, idempotency, and caching

A pair of birth records should always return the same score, which makes results highly cacheable. Practical guidance for a matrimony backend:

Cache by a stable key. Hash the two normalized birth records (datetime, lat, lng, timezone) into a single key. Order-normalize the pair so (A,B) and (B,A) hit the same cache entry where the system is symmetric.
Use idempotency on any billed call. Send an Idempotency-Key header on retries so a network blip never double-charges or double-computes.
Pre-compute on profile creation. Charts are deterministic from birth data, so compute and store each user's natal summary once; pair-scoring then only needs the two stored summaries.

Pricing for a matchmaking workload

Matrimony traffic is bursty — heavy during onboarding and when users browse matches, quiet otherwise — so a wallet-credit model fits better than fixed per-seat licensing. Plans start at Starter $12/mo, then Professional $60, Business $120 (adds the fast path and voice), and Enterprise $240, with per-query costs of $0.01–$0.05. Competing astrology APIs are priced in a similar band — Prokerala around $19, AstrologyAPI.com around $29, RoxyAPI around $39 — and each has genuine strengths in their established endpoint catalogs. Vedika's differentiators for this use case are three-systems-in-one-API, the open-source precision engine, and source-cited interpretations. You can validate the request and response shapes against the free sandbox (no key required) before you commit.

Sourced interpretations, not invented verses

For a matrimony product, an incorrect citation is worse than no citation — it erodes trust with the exact users who care most. Vedika's interpretive layer is constrained to classical sources actually used in Jyotish, KP, and Western training: BPHS, Phaladeepika, Saravali, Jataka Parijata, the Jaimini Sutras, the KP Readers, and Ptolemy's Tetrabiblos. Where a particular compatibility nuance has no clean sourced rule, the API returns the computed factors without fabricating a verse or a percentage. That conservatism is deliberate.

Key facts

Base URL https://api.vedika.io; auth via x-api-key: vk_live_*.
AI endpoint POST /api/v1/astrology/query accepts a question plus birthDetails (and partner details) and returns a grounded answer; /v2/astrology/* exposes flat-field computation.
Three matching systems in one API: Vedic Ashtakoota (36-guna) + Manglik, Western synastry, and KP compatibility.
Charts compute on the open-source XALEN Ephemeris (Apache-2.0; crates.io, PyPI, npm WASM) validated against JPL DE440 and swetest, within 0.1° across a reproducible JPL DE440 benchmark.
Compatibility results are deterministic and cacheable; use an Idempotency-Key on billed retries.
30 languages (14 Indic) and 700+ operations across 25 domains, so a match score can scale up to full kundli reports.
Pricing $12–$240/mo plus $0.01–$0.05 per query; free sandbox with no key.

From match score to full experience

Once compatibility scoring works, the same API lets a matrimony platform layer on the features that improve retention: a full guna milan report PDF, individual kundli pages on each profile, daily transit-based "good day to message" nudges, and panchang-driven auspicious-date suggestions for engagement or wedding planning. Because all of it runs on one contract and one billing wallet, the integration footprint stays small. Start in the sandbox, read the API docs for the exact response fields, and review plans to size your volume.

FAQ

Does the API return a guna milan score out of 36?

Yes. The Vedic Ashtakoota system scores eight kootas for a maximum of 36 gunas, and the API returns the per-koota points, the aggregate, and Bhakoot/Nadi dosha flags computed from both partners' Moon-sign and nakshatra placements.

Can it check Manglik (Mangal Dosha) status for both partners?

Yes. Manglik analysis evaluates Mars placement across the relevant houses and checks cancellation conditions for each partner. The matching path requires a real Mars basis for both charts before returning a verdict, so a missing chart is never treated as "no dosha".

Can I use Western or KP compatibility instead of Vedic?

Yes. The same base URL exposes Western synastry (aspect grids, house overlays, composite midpoints) and KP sub-lord compatibility, selectable per request, so you don't integrate separate vendors for different traditions.

Are compatibility scores deterministic and cacheable?

Yes. A given pair of normalized birth records always produces the same score, so you can cache by a hash of the two records and use an Idempotency-Key on billed retries to avoid double-charging.

How accurate are the underlying charts?

Charts compute on the open-source XALEN Ephemeris, validated against JPL DE440 and the swetest reference tool with no chart deviating beyond 0.1° across a reproducible JPL DE440 benchmark. That is astronomical precision for planetary positions; astrological interpretation is separately constrained to classical sources.