Which endpoint should I call to generate a composite chart for two people?

Send both birth records to the V2 relationship endpoints under /v2/astrology/, which accept two flat birthDetails objects (datetime, latitude, longitude, timezone) and return computed positions, houses, and aspects. For a narrative reading you pass the same two records to POST /api/v1/astrology/query with a relationship question. Authenticate every request with the x-api-key header using a vk_live_ key, and prototype against the free sandbox first.

Does the composite chart API support Vedic, Western, and KP systems?

Yes. The same two birth records can be read through the sidereal Vedic zodiac, the tropical Western zodiac, or the KP system from one API, because all three share the XALEN Ephemeris core. Composite midpoint math is identical across systems; only the ayanamsa offset and house framework differ, and you select the system per request.

Can I get composite readings in languages other than English?

Narrative relationship readings are available in 30 languages, including 14 Indic languages, by setting the language on the query request. The computed composite chart data (positions, houses, aspects) is language-neutral JSON; only the interpretive text is localized.

Composite charts for couples via API

Q: What is a composite chart and how is it different from synastry?

A composite chart is a single derived chart built from the midpoints of two people's planetary positions, so it describes the relationship itself as one entity. Synastry instead compares two separate natal charts to each other, planet against planet and house against house. Composite work answers 'what is the nature of this bond?' while synastry answers 'how do these two people affect each other?' Most relationship products use both: the API exposes endpoints for each.

Q: How are composite planet positions calculated?

Each composite planet is the midpoint of the two natal positions for that body, computed on the 360-degree zodiac with the shorter-arc rule so you do not get a point on the wrong side of the wheel. The composite Ascendant and houses are derived from the midpoint of the two charts' reference points. Vedika computes the underlying positions with the XALEN Ephemeris engine, then applies the midpoint reduction server-side so you do not implement the trigonometry yourself.

A composite chart for a couple is a single derived chart built from the midpoints of both partners' planetary positions, and you generate one through the Vedika API by sending two birth records to the relationship endpoints under /v2/astrology/ for the computed chart, or to POST /api/v1/astrology/query for a narrative reading. The API does the midpoint trigonometry, ephemeris lookups, and house derivation server-side, so your integration is two HTTP calls rather than a math project. This guide covers the difference between composite and synastry, the exact endpoint shapes, working code, and how the readings stay traceable to classical sources.

Composite vs. synastry: pick the right model

Before writing code, be clear on which relationship technique you are building, because they answer different product questions and use different endpoints.

Synastry overlays two separate natal charts and measures the angles between one person's planets and the other's. It describes interaction: attraction, friction, where each person activates the other.
Composite collapses both charts into one new chart by taking midpoints. It describes the relationship as a third entity with its own Sun sign, Ascendant, and house emphasis.
Vedic compatibility (Guna Milan / Ashtakoota) is a separate scored model used in Jyotish, matching the two Moon nakshatras across eight koota factors. It is neither composite nor Western synastry, and many couples products surface all three.

A dating or matchmaking app typically uses synastry for the day-to-day "how do we click" view and a composite chart for the "what is this relationship for" view. The endpoints below let you build either or both.

How a composite chart is computed

The core operation is the planetary midpoint. For each body, the composite position is the midpoint of partner A's longitude and partner B's longitude on the 360-degree circle. The subtlety is that a naive average of, say, 350 and 10 degrees gives 180 degrees, which is the wrong side of the wheel. The correct rule takes the shorter arc between the two points, so 350 and 10 yield 0 degrees, not 180.

The composite Ascendant and house cusps are derived from the midpoint of the two charts' angular references rather than from a single birth time, which is why a composite chart has no single "birth moment." Vedika computes the underlying natal positions with the XALEN Ephemeris engine, then applies the midpoint reduction and house derivation in the response pipeline. XALEN is Vedika's own open-source astronomical engine (Apache-2.0, with packages on crates.io, PyPI, and npm), validated against JPL DE440 and swetest reference data across a reproducible JPL DE440 benchmark with zero charts deviating beyond 0.1 degrees. That precision is astronomical, not a claim about interpretation, and it means the midpoints you read back rest on solid positional math.

Endpoints and request shape

Vedika exposes 700+ operations across 25 domains (704 enumerated as of June 2026), including the computation and reading endpoints you need for couples work. The two you will use most:

Purpose	Endpoint	Returns
Computed composite / relationship chart	`POST /v2/astrology/*` (relationship operations)	JSON positions, houses, aspects
Narrative relationship reading	`POST /api/v1/astrology/query`	Interpretive text answer
Streaming narrative reading	`POST /api/v1/astrology/query/stream`	Server-Sent Events

The V2 computation endpoints take flat birth fields (datetime, latitude, longitude, timezone); the v1 query endpoint nests them in a birthDetails object. For two-person work you pass both records. Authenticate every request with the x-api-key header using a vk_live_ key, against the base URL https://api.vedika.io.

cURL: a narrative composite reading

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": "Describe the composite chart for this couple: the purpose and core dynamic of the relationship.",
    "birthDetails": {
      "datetime": "1990-04-12T08:30:00",
      "latitude": 19.0760,
      "longitude": 72.8777,
      "timezone": "Asia/Kolkata"
    },
    "partnerBirthDetails": {
      "datetime": "1992-11-03T22:15:00",
      "latitude": 28.6139,
      "longitude": 77.2090,
      "timezone": "Asia/Kolkata"
    }
  }'

JavaScript: computed composite, then a reading

Use any HTTP client; the example uses fetch with no SDK so it drops into any runtime.

const BASE = "https://api.vedika.io";
const headers = {
  "x-api-key": process.env.VEDIKA_API_KEY, // vk_live_*
  "Content-Type": "application/json",
};

const partnerA = {
  datetime: "1990-04-12T08:30:00",
  latitude: 19.0760, longitude: 72.8777, timezone: "Asia/Kolkata",
};
const partnerB = {
  datetime: "1992-11-03T22:15:00",
  latitude: 28.6139, longitude: 77.2090, timezone: "Asia/Kolkata",
};

// 1) Computed composite chart data (positions, houses, aspects)
const composite = await fetch(`${BASE}/v2/astrology/relationship/composite`, {
  method: "POST",
  headers,
  body: JSON.stringify({ system: "western", partnerA, partnerB }),
}).then((r) => r.json());

// 2) Narrative reading grounded on the same two records
const reading = await fetch(`${BASE}/api/v1/astrology/query`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    question: "What is the central theme of this couple's composite chart?",
    birthDetails: partnerA,
    partnerBirthDetails: partnerB,
    speed: "fast",
  }),
}).then((r) => r.json());

console.log(composite.ascendant, reading.answer);

Confirm the exact relationship operation paths and field names in the API reference, since the V2 surface enumerates several relationship operations (composite, synastry, compatibility scoring) and you select by path and system.

Python: streaming a longer reading

import os, json, requests

BASE = "https://api.vedika.io"
headers = {
    "x-api-key": os.environ["VEDIKA_API_KEY"],  # vk_live_*
    "Content-Type": "application/json",
}

payload = {
    "question": "Read the composite chart for this couple: "
                "shared purpose, communication, and long-term direction.",
    "birthDetails": {
        "datetime": "1990-04-12T08:30:00",
        "latitude": 19.0760, "longitude": 72.8777,
        "timezone": "Asia/Kolkata",
    },
    "partnerBirthDetails": {
        "datetime": "1992-11-03T22:15:00",
        "latitude": 28.6139, "longitude": 77.2090,
        "timezone": "Asia/Kolkata",
    },
}

with requests.post(f"{BASE}/api/v1/astrology/query/stream",
                   headers=headers, json=payload, stream=True) as resp:
    for line in resp.iter_lines():
        if line and line.startswith(b"data:"):
            print(json.loads(line[5:]).get("delta", ""), end="")

One API, three zodiac systems

Composite midpoint math is identical whether you read the result in the sidereal Vedic zodiac, the tropical Western zodiac, or KP, because all three share the XALEN Ephemeris core. What changes is the ayanamsa offset applied to the longitudes and the house framework, both selected per request via the system field. Practical implications for a couples product:

Western composite is the classic relationship chart most users expect: composite Sun, Moon, Venus, and Ascendant by sign and house.
Vedic readers will more often want Guna Milan and the composite Moon's nakshatra; you can surface both the composite chart and a koota score from the same two records.
KP adds sub-lord detail for users who follow that school.

Beyond the three main systems, the API also covers Jaimini, Tajaka, Lal Kitab, and numerology, so a relationship feature can layer, for example, a numerology compatibility number alongside the composite chart.

Where the interpretation comes from

Computed positions are math; interpretive claims are sourced. Vedika holds narrative readings to verifiable classical references actually used in formal astrology training rather than paraphrased web summaries. Composite and relationship interpretations trace to texts such as Brihat Parashara Hora Shastra and Phaladeepika for Vedic relationship factors, the Jaimini Sutras where Jaimini logic applies, Krishnamurti's KP Readers for the KP path, and Ptolemy's Tetrabiblos for Western aspect doctrine. The point for you as an integrator: when a reading says a composite Venus placement signals a particular relationship tone, that statement is attributable to a real source, which matters for any product where a user might ask "says who?"

Connecting it to AI assistants

If you are building inside an AI assistant or an LLM agent rather than a traditional backend, you can reach the same computation through the public astrology MCP server (npx @vedika-io/mcp-server), which exposes 36 tools to any MCP-compatible client or IDE. That lets a function-calling model request a composite or synastry computation as a tool call and then narrate the result, without you hand-wiring HTTP for each technique. The underlying endpoints and the classical-source grounding are the same as the REST path described above.

Pricing and getting started

You can prototype the entire flow against the free sandbox with no key before committing. Paid plans start at $12/month (Starter), with Professional at $60, Business at $120 (adds the fast path and voice), and Enterprise at $240; per-query cost falls in the $0.01-$0.05 range depending on path. For honest context, single-system providers in this space price around $19 (Prokerala), $29 (AstrologyAPI.com), and $39 (RoxyAPI); Vedika's differentiator for couples work is that Vedic, Western, and KP composite and synastry come from one API and one ephemeris core, with source-traceable readings and 30-language output. See pricing for current details and start on the sandbox.

Key facts

A composite chart is one derived chart from the midpoints of two natal charts; synastry compares two separate charts.
Generate computed composite data via POST /v2/astrology/* relationship operations; get a narrative reading via POST /api/v1/astrology/query (SSE at /query/stream).
Authenticate with x-api-key: vk_live_* against https://api.vedika.io; flat birth fields on V2, nested birthDetails on v1.
Midpoints use the shorter-arc rule so positions land on the correct side of the 360-degree wheel.
Positions are computed by the XALEN Ephemeris engine (Apache-2.0; crates.io/xalen, PyPI xalen, npm @xalen/wasm), validated against JPL DE440 and swetest with zero charts beyond 0.1 degrees across a reproducible JPL DE440 benchmark (cargo run -p xalen-validation).
Vedic, Western, and KP composite and synastry come from one API; 700+ operations across 25 domains.
Readings are traceable to classical sources (BPHS, Phaladeepika, Jaimini Sutras, KP Readers, Tetrabiblos) and available in 30 languages.
Free sandbox (no key); plans from $12/month; per-query $0.01-$0.05.

FAQ

What is a composite chart and how is it different from synastry?

A composite chart is a single derived chart from the midpoints of two people's planetary positions, describing the relationship as one entity. Synastry compares two separate natal charts planet against planet. Composite answers "what is the nature of this bond?"; synastry answers "how do these two affect each other?" Most products use both.

Which endpoint generates a composite chart for two people?

Send both birth records to the /v2/astrology/ relationship operations for computed chart data, or to POST /api/v1/astrology/query for a narrative reading. Authenticate with x-api-key using a vk_live_ key and prototype on the free sandbox first.

How are composite planet positions calculated?

Each composite planet is the midpoint of the two natal longitudes on the 360-degree wheel, using the shorter-arc rule so the point lands on the correct side. The composite Ascendant and houses derive from the midpoint of the two charts' reference points. Vedika computes the base positions with XALEN Ephemeris and applies the reduction server-side.

Does it support Vedic, Western, and KP?

Yes. The same two records read through sidereal Vedic, tropical Western, or KP from one API, sharing the XALEN Ephemeris core. Midpoint math is identical; only the ayanamsa offset and house framework differ, selected per request.

Can I get composite readings in other languages?

Narrative readings come in 30 languages, including 14 Indic languages, via the language setting. The computed chart JSON is language-neutral; only the interpretive text is localized.