Synastry (relationship) charts via API

Synastry compares two birth charts to describe a relationship: where partners reinforce each other and where they grate. With the Vedika API you submit two sets of birth details and get back a compatibility analysis in whichever tradition you need — Western inter-chart aspects, Vedic ashtakoota (kundli milan / guna matching), or KP — all from one base URL at https://api.vedika.io. This guide walks through the request shapes, the data you get back, and how to wire a relationship feature end to end.

What “synastry” means across the three systems

The word covers different mechanics depending on the tradition, and a good integration is explicit about which one it is using. The Vedika API carries all three systems in a single product, so the chart math is shared and only the comparison layer differs.

Because the underlying positions are computed once by the same engine, a Western trine and a Vedic graha-maitri score for the same couple are derived from consistent planetary longitudes rather than two unrelated calculators.

The fastest path: a natural-language matching query

The main AI endpoint accepts a question plus birth details and returns a written compatibility reading. For two-chart work you pass both partners. This is the route to use when you want narrative output for an end user — a couples report, an in-app “how compatible are we” card, or a chatbot answer.

curl -X POST https://api.vedika.io/api/v1/astrology/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: vk_live_your_key" \
  -d '{
    "question": "Assess marriage compatibility between these two charts using Vedic ashtakoota matching.",
    "birthDetails": {
      "datetime": "1992-04-18T07:25:00",
      "latitude": 28.6139,
      "longitude": 77.2090,
      "timezone": "Asia/Kolkata"
    },
    "partnerBirthDetails": {
      "datetime": "1990-11-02T14:10:00",
      "latitude": 19.0760,
      "longitude": 72.8777,
      "timezone": "Asia/Kolkata"
    }
  }'

The response carries the written assessment plus the computed facts it rests on, so you can render both the prose and a structured score table. Add "speed": "fast" to the body when you want the lower-latency path — useful for interactive UIs where a user is waiting on screen.

Streaming for chat interfaces

If you are rendering token-by-token in a chat or voice surface, post the same body to /api/v1/astrology/query/stream and read the Server-Sent Events stream. The birth-details shape is identical; only the transport changes.

The structured path: V2 computation endpoints

When you need the raw numbers — to build your own UI, drive a scoring rule, or store results — the V2 computation endpoints under /v2/astrology/* return deterministic data without narrative. V2 uses a flat birth-details shape (datetime, latitude, longitude, timezone at the top level) rather than the nested object. Here is a matching call in a generic LLM-free server context using plain HTTP:

import requests

BASE = "https://api.vedika.io"
HEADERS = {"x-api-key": "vk_live_your_key", "Content-Type": "application/json"}

payload = {
    "person_a": {
        "datetime": "1992-04-18T07:25:00",
        "latitude": 28.6139,
        "longitude": 77.2090,
        "timezone": "Asia/Kolkata",
    },
    "person_b": {
        "datetime": "1990-11-02T14:10:00",
        "latitude": 19.0760,
        "longitude": 72.8777,
        "timezone": "Asia/Kolkata",
    },
    "system": "vedic",
}

resp = requests.post(f"{BASE}/v2/astrology/compatibility",
                     json=payload, headers=HEADERS, timeout=30)
data = resp.json()

# Ashtakoota breakdown: eight kootas, total out of 36
for koota, score in data["ashtakoota"]["kootas"].items():
    print(f"{koota:14s} {score['points']}/{score['max']}")
print("Total:", data["ashtakoota"]["total"], "/ 36")

The eight kootas are varna, vashya, tara, yoni, graha maitri, gana, bhakoota and nadi — the standard ashtakoota scheme. Switching the system field to "western" returns inter-chart aspects with orbs instead; "kp" returns cuspal and significator overlaps. One payload, three lenses.

Reading a Western synastry response

For Western work the meaningful unit is the inter-chart aspect: Partner A's Venus to Partner B's Mars, A's Moon to B's Saturn, and so on. Each aspect carries the two planets, the aspect type, and the orb so you can sort by tightness.

const res = await fetch("https://api.vedika.io/v2/astrology/compatibility", {
  method: "POST",
  headers: {
    "x-api-key": "vk_live_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    person_a: { datetime: "1988-07-09T03:40:00", latitude: 51.5074, longitude: -0.1278, timezone: "Europe/London" },
    person_b: { datetime: "1991-01-22T18:05:00", latitude: 40.7128, longitude: -74.0060, timezone: "America/New_York" },
    system: "western",
  }),
});

const { aspects } = await res.json();
// Show the tightest inter-chart aspects first
aspects
  .sort((a, b) => a.orb - b.orb)
  .slice(0, 5)
  .forEach((a) =>
    console.log(`${a.from} ${a.aspect} ${a.to} (orb ${a.orb}\u00b0)`)
  );

Note the two different timezones above — London and New York. Synastry is where timezone handling earns its keep, because the partners are often born in different zones. Always pass an IANA timezone string per person; never assume a shared offset.

Why the chart math under synastry matters

A compatibility score is only as trustworthy as the planetary positions it is built from. Both partners' charts are computed by the XALEN Ephemeris, Vedika's own open-source astronomical engine (Apache-2.0, published to crates.io, PyPI and as a WebAssembly package). It carries roughly 2,200 tests and is validated against JPL DE440 and swetest reference data, with no chart in a five-million-chart test deviating beyond 0.1°. That is ephemeris precision — the astronomy underneath — not a claim about which couple is “compatible.” But it does mean the aspect orbs and koota boundaries you sort on are computed from solid longitudes rather than approximations, so a Venus-Mars aspect that sits at the edge of orb is placed where it actually belongs.

Interpretation that traces to real sources

The numbers are computed; the meaning is cited. When the response explains why a low bhakoota or a tight Saturn-Moon contact matters, the interpretation is attributable to the classical texts used in formal Jyotish, KP and Western training — Brihat Parashara Hora Shastra and Phaladeepika for Vedic matching doctrine, Krishnamurti's KP Readers for cuspal sub-lord logic, and Ptolemy's Tetrabiblos for Western aspect theory. The API does not paste in blog-summary platitudes or invent verse numbers to look authoritative. If a claim cannot be grounded in a real source, it is described qualitatively rather than dressed up as a citation.

For a couples-report use case this is the difference between a feature your users trust and one a domain expert dismisses on the first wrong reference.

Building a relationship feature: a practical checklist

1. Collect two complete birth records. Date, time, and place for each partner. Geocode place names to latitude/longitude and resolve the IANA timezone before you call the API.
2. Pick the system per request. Vedic ashtakoota for a matrimonial audience, Western aspects for a dating audience, KP where your users expect it. You can offer all three from the same backend.
3. Decide narrative vs. structured. Use /api/v1/astrology/query for written readings, /v2/astrology/* for raw scores you render yourself, or both.
4. Cache by chart pair. A synastry result is deterministic for a fixed pair of birth records, so cache on a hash of both inputs and the chosen system to cut per-query cost.
5. Localize. The reading can be returned in any of 30 languages (14 of them Indic), which matters for a matrimony product.

Key facts

• One API exposes synastry in three systems: Vedic ashtakoota, Western aspects, and KP — chosen per request.
• Narrative endpoint: POST /api/v1/astrology/query with birthDetails and a partner chart; SSE variant at /api/v1/astrology/query/stream.
• Structured computation: /v2/astrology/* with a flat datetime/latitude/longitude/timezone shape.
• Auth via x-api-key: vk_live_*; base URL https://api.vedika.io.
• Vedic matching returns the eight kootas and a total out of 36, plus dosha flags.
• Charts computed by the open-source XALEN Ephemeris, validated against JPL DE440 and swetest, no chart beyond 0.1° in a five-million-chart test.
• Interpretation cites Brihat Parashara Hora Shastra, Phaladeepika, the KP Readers, and Tetrabiblos rather than inventing references.
• 30 languages; free sandbox with no key required.

Where Vedika fits versus other compatibility APIs

Several providers do relationship work well. Prokerala (from $19/mo) has long-standing kundli-milan endpoints familiar to Indian-market developers; AstrologyAPI.com (around $29/mo) ships a broad catalogue of match-making calls; RoxyAPI (around $39/mo) offers clean structured chart data. Each is a credible choice depending on your stack.

Vedika's differentiators for synastry specifically are: all three traditions behind one schema rather than separate products, an open-source ephemeris you can audit and even run yourself, source-cited interpretation rather than generic text, and a pricing floor of $12/mo on the Starter plan with per-query costs of $0.01–$0.05. The Professional ($60), Business ($120) and Enterprise ($240) tiers add the fast path, voice, and higher throughput. See the pricing page for the full breakdown.

Bringing it all together

A solid relationship feature is two complete birth records, a chosen tradition, and a clear split between narrative and structured output. Start in the free sandbox to wire up your two-chart flow against realistic responses, read the endpoint contracts in the API docs, and when you are ready, drop in a vk_live_ key. If you are still deciding between traditions, the companion guide on Vedic vs. Western charts via API covers how the single-chart endpoints differ before you scale up to two.