Kaal Sarp Dosha analysis via astrology API

To analyse Kaal Sarp Dosha through an astrology API, compute a sidereal chart for the birth details, then test whether all seven classical planets fall within the 180-degree arc that runs from Rahu to Ketu. With the Vedika API you can do this two ways: pull raw planetary longitudes from the V2 computation endpoints and run the check yourself, or send the birth details and a question to POST /api/v1/astrology/query and receive a narrated verdict, the named type, and source-cited remedial guidance. This article walks through both, with the real endpoint shapes.

What Kaal Sarp Dosha actually is

Rahu and Ketu, the lunar nodes, are always exactly 180 degrees apart. They divide the zodiac into two halves. Kaal Sarp Dosha is the condition where every one of the seven graha — Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn — sits on a single side of that axis, leaving the other half empty of planets. The configuration is read through the houses and signs the Rahu-Ketu axis occupies, and through whether the planets are hemmed moving from Rahu toward Ketu in zodiacal order.

This is a Vedic concept rooted in the treatment of the nodes as chaya graha (shadow planets) in classical Jyotish. Because it depends on sidereal node positions, the detection runs against the sidereal chart even though the same API can also return tropical and KP charts from the same request.

The seven checks behind the verdict

A correct detection is not a single boolean — it is a sequence of computed checks. Each one is pure arithmetic over the chart, never guessed:

1. Node longitudes — resolve Rahu and Ketu to their sidereal ecliptic longitudes.
2. Arc membership — for each of the seven planets, test whether it lies in the half-circle from Rahu to Ketu (measured in zodiacal order).
3. Full enclosure — the dosha is present only if all seven are on the same side.
4. Partial vs complete — if a planet sits exactly on the axis or just across it, the configuration is partial, which classical practice treats more leniently.
5. Rahu's house — determines the named type (see below).
6. Direction — whether planets run Rahu→Ketu (often described as the rising or udita form) or the reverse.
7. Cancellation factors — node placement, aspects, and exaltation that classical literature weighs before pronouncing severity.

The twelve named types

The specific name of a Kaal Sarp configuration is fixed by the house Rahu occupies. Knowing the house lets you label the type deterministically:

Because the V2 chart response gives you Rahu's house number, you can derive the type with a single lookup. The natural-language query endpoint names it for you.

Path 1: compute the chart and run the check yourself

If you already have a charting layer and just want the node positions, hit the V2 computation surface. These endpoints take flat parameters (datetime, latitude, longitude, timezone) and return precise longitudes for all nine bodies. They are deterministic ephemeris math, which makes them ideal for the dosha test.

curl -X POST https://api.vedika.io/v2/astrology/chart \
  -H "x-api-key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-08-15T06:30:00",
    "latitude": 18.5204,
    "longitude": 73.8567,
    "timezone": "Asia/Kolkata",
    "system": "vedic"
  }'

With the longitudes in hand, the enclosure test is a few lines. The key is to walk the arc from Rahu in zodiacal order and confirm every planet is reached before you hit Ketu:

// planets: { rahu, ketu, sun, moon, mars, mercury, jupiter, venus, saturn }
// each value is a sidereal longitude in degrees [0, 360)
function kaalSarpVerdict(p) {
  const seven = ['sun','moon','mars','mercury','jupiter','venus','saturn'];
  // arc length travelling forward from Rahu to Ketu
  const arc = (deg) => ((p[deg] - p.rahu) % 360 + 360) % 360;
  const ketuArc = arc('ketu'); // ~180 by construction
  const sameSide = seven.every((name) => arc(name) < ketuArc);
  return {
    present: sameSide,
    // partial if any planet sits within ~1 degree of either node
    partial: seven.some((name) => {
      const a = arc(name);
      return a < 1 || Math.abs(a - ketuArc) < 1;
    }),
  };
}

This is the honest core of every Kaal Sarp engine. The interpretation that follows — type, severity, life-area emphasis — is layered on top of this computed verdict, never used to fabricate it.

Why the ephemeris underneath matters

A dosha that hinges on a 180-degree node split is sensitive to node precision. The node positions come from the XALEN Ephemeris, Vedika's own open-source astronomical engine (Apache-2.0, published on crates.io, PyPI and npm, with roughly 2,200 tests). It has been validated against JPL DE440 and swetest, with zero charts deviating beyond 0.1 degrees across a five-million-chart test. That is ephemeris precision — the astronomy underneath — which is exactly what you want a node-axis test to stand on.

Path 2: ask for the interpretation directly

Most integrations do not want to reimplement Jyotish judgement. The main AI endpoint takes the birth details and a question and returns a narrated answer. For Kaal Sarp it names the type, states whether the configuration is full or partial, and gives remedial guidance attributed to classical literature.

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": "Do I have Kaal Sarp Dosha, and which type? What does it mean?",
    "birthDetails": {
      "datetime": "1990-08-15T06:30:00",
      "latitude": 18.5204,
      "longitude": 73.8567,
      "timezone": "Asia/Kolkata"
    }
  }'

In Python, the same call against the streaming variant lets you render the answer token by token in a UI:

import requests

resp = requests.post(
    "https://api.vedika.io/api/v1/astrology/query/stream",
    headers={"x-api-key": "vk_live_your_key_here"},
    json={
        "question": "Explain my Kaal Sarp Dosha and remedies.",
        "birthDetails": {
            "datetime": "1990-08-15T06:30:00",
            "latitude": 18.5204,
            "longitude": 73.8567,
            "timezone": "Asia/Kolkata",
        },
        "speed": "fast",
    },
    stream=True,
)
for line in resp.iter_lines():
    if line:
        print(line.decode())  # Server-Sent Events frames

The optional speed: "fast" flag routes the request through Vedika Swift for lower latency when you are powering an interactive widget; omit it for the standard depth path. Whichever you choose, the dosha verdict itself is computed from the chart before any language is generated.

Keeping the claims sourced

The reason to use a dedicated astrology API rather than a general text model for this is provenance. Every astrological assertion in the interpretation is meant to trace to texts that practitioners actually train on — Brihat Parashara Hora Shastra, Phaladeepika, Saravali and the like — not to a paraphrase scraped from the open web. When a specific remedy or severity claim cannot be grounded in such a source, the response withholds the assertion instead of bluffing a citation. For a node-axis condition that is frequently over-dramatised online, that restraint is the feature.

Where Kaal Sarp fits in the wider API

Kaal Sarp detection is one small piece of a much larger surface: 600 plus operations across 25 domains (704 enumerated as of June 2026), covering Vedic, Western and KP from a single integration, alongside Jaimini, Tajaka, Lal Kitab and numerology. The same account that runs your dosha checks can compute dashas, yogas, divisional charts, and panchang, and respond in 30 languages including 14 Indic ones. There is also a public astrology MCP server (npx @vedika-io/mcp-server, 36 tools) if you want an LLM agent or an MCP-compatible client to call these capabilities as tools.

How it compares

Several established providers serve dosha endpoints well. Prokerala (from around $19/month) is a long-standing, well-documented option; AstrologyAPI.com (from around $29/month) has broad Vedic coverage; RoxyAPI (from around $39/month) is a capable computation service. Credit where due — those are solid products. Vedika's differentiators for this specific use case are the open-source, independently testable ephemeris underneath the node positions, the three chart systems behind one request shape, the source-citation discipline on interpretive claims, and the MCP server for agent integration. You can verify the behaviour before spending anything on the free sandbox (no key required).

Key facts

• Kaal Sarp Dosha is present when all seven classical planets fall on one side of the Rahu-Ketu axis (the nodes are always 180 degrees apart).
• The named type (Anant through Sheshnag) is fixed by the house Rahu occupies.
• Compute longitudes via POST /v2/astrology/chart (flat datetime/latitude/longitude/timezone) and run the arc-enclosure test yourself.
• Or get a narrated, source-cited verdict via POST /api/v1/astrology/query; stream it at /api/v1/astrology/query/stream.
• Detection runs on the sidereal chart; the same API also serves Western tropical and KP charts.
• Node precision rests on the open-source XALEN Ephemeris, validated against JPL DE440 with no chart beyond 0.1 degrees across a five-million-chart test.
• Auth via x-api-key: vk_live_*; base URL https://api.vedika.io; per-query cost roughly $0.01–$0.05.

Get started

Try the call shapes above against the free sandbox first, then review plans on the pricing page (Starter $12/mo through Enterprise $240/mo). Full request and response schemas, including the V2 computation surface, live in the API documentation. If you are building a dosha or compatibility feature, the same patterns extend to Mangal Dosha, Sade Sati and guna matching covered in the Vedic astrology API guide.