Vimshottari Dasha, explained for API developers

Vimshottari Dasha is the most widely used planetary-timing system in Vedic astrology: a 120-year cycle that assigns consecutive periods to the nine grahas, anchored to the Moon's position at birth. Through the Vedika API you can compute the full nested timeline (major periods, sub-periods, and deeper) from a birth datetime and location, and optionally turn it into a cited, plain-language reading. This guide explains how the system works, why your inputs matter so much, and how to call it cleanly.

What Vimshottari Dasha actually is

Unlike a natal chart, which is a snapshot, a dasha is a sequence over time. Vimshottari divides a 120-year cycle among the nine grahas, each holding a fixed allotment: Ketu 7 years, Venus 20, Sun 6, Moon 10, Mars 7, Rahu 18, Jupiter 16, Saturn 19, and Mercury 17. Those add to 120. The order is fixed, but where a given chart enters the cycle is not.

The entry point is set by the Moon. At birth, the Moon sits in one of the 27 nakshatras, and each nakshatra is ruled by one of the nine grahas in that same repeating order. The ruler of the birth Moon's nakshatra owns the first Mahadasha, and the fraction of that nakshatra the Moon has already traversed determines how much of that first period is already spent — the "balance of dasha" at birth.

This is described in the foundational Jyotish text Brihat Parashara Hora Shastra, which treats Vimshottari as the primary dasha system among many. The classical framing matters for an API: the math is deterministic, but it is a model with documented rules, not a black box.

Why the inputs are unforgiving

Because everything hinges on the Moon's exact sidereal longitude, the calculation is sensitive to inputs in a way that a sun-sign lookup is not. The Moon moves roughly 13 degrees a day, so a one-hour error in birth time can move it noticeably within a nakshatra and change the starting balance — which then cascades through every period boundary for the rest of the life. Three inputs drive correctness:

• Birth time — shifts the Moon's longitude and therefore the dasha balance.
• Location (latitude, longitude) — needed for the chart and house frame, and to resolve local time correctly.
• Timezone — a mismatch here is the most common cause of "my numbers are off by a few years" reports.

The nested levels: Maha, Antar, Pratyantar

Vimshottari is fractal. Each major period subdivides into the same nine-graha order, scaled to the parent's length. That gives you levels you can render to whatever resolution a UI needs:

The proportional rule is consistent at every level: a sub-period's length is the parent length multiplied by (sub-graha's allotment / 120). So within a 16-year Jupiter Mahadasha, the Saturn Antardasha runs 16 × (19 / 120) years. Building a timeline component is then just a recursive walk: start date plus accumulated durations, descending as deep as you want.

Designing around the levels

Most product surfaces need only the first two or three levels. A "current period" badge needs the Mahadasha and Antardasha active today; a life-timeline view needs all Mahadashas with Antardashas expandable on click. Pulling Pratyantardasha for the whole life upfront is usually wasted payload — compute the deeper levels lazily for the period the user is actually inspecting.

Computing it through the API

Vedika exposes both raw computation and AI-grounded interpretation across 700+ operations spanning 25 domains. For dasha work you typically want the structured computation endpoints under /v2/astrology/*, which take flat birth fields and return machine-readable period data.

Every request authenticates with an API key header. The base URL is https://api.vedika.io, and you can explore the shapes against the free sandbox before wiring a live key.

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

The response gives you the ordered Mahadasha list with start and end dates, the active period, and nested sub-periods you can descend into. From there, rendering a timeline is straightforward:

const res = await fetch("https://api.vedika.io/v2/astrology/dasha", {
  method: "POST",
  headers: {
    "x-api-key": process.env.VEDIKA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    datetime: "1990-08-15T14:30:00",
    latitude: 18.5204,
    longitude: 73.8567,
    timezone: "Asia/Kolkata",
  }),
});

const { mahadashas } = await res.json();

// Find the period active today
const now = new Date();
const current = mahadashas.find(
  (d) => new Date(d.start) <= now && now < new Date(d.end)
);
console.log(`Current Mahadasha: ${current.lord}`);

From numbers to a reading

Period boundaries answer "when"; they do not answer "what does this period mean for this chart." For that, POST /api/v1/astrology/query takes a natural-language question plus nested birth details and returns a written interpretation grounded in the same computed chart. It accepts an optional speed: "fast" flag, and a streaming variant at /api/v1/astrology/query/stream delivers tokens over SSE for chat-style UIs.

import requests

resp = requests.post(
    "https://api.vedika.io/api/v1/astrology/query",
    headers={"x-api-key": "vk_live_your_key_here"},
    json={
        "question": "What does my current Mahadasha emphasise this year?",
        "birthDetails": {
            "datetime": "1990-08-15T14:30:00",
            "latitude": 18.5204,
            "longitude": 73.8567,
            "timezone": "Asia/Kolkata",
        },
    },
)
print(resp.json())

The interpretation path is built so that astrological claims trace back to real classical sources rather than being invented on the fly. Timing statements draw on the same texts that practitioners are trained from — Brihat Parashara Hora Shastra and Phaladeepika among them — instead of paraphrased blog summaries.

The accuracy question, honestly framed

There are two different kinds of "accuracy" people conflate, and keeping them separate saves a lot of confusion.

The first is astronomical precision: where the planets actually were. Vedika computes positions with the XALEN Ephemeris, its own open-source engine (Apache-2.0, available on crates.io, PyPI, and as a WebAssembly package), backed by roughly 2,200 tests. It has been validated against reference astronomical data including JPL DE440 and the swetest reference tool, with no charts deviating beyond 0.1 degrees across a multi-million-chart sweep. That is the layer that decides exactly which nakshatra the Moon occupies — and therefore your dasha balance.

The second is astrological interpretation, which is a tradition of meaning, not a measurable quantity. No API can claim a "correct" reading. What an API can do is keep the computation deterministic and the interpretation honestly sourced. Vedika does both, and is explicit that ephemeris precision is an astronomical claim, not a guarantee about predictions.

Ayanamsa: the silent variable

Sidereal systems subtract an offset, the ayanamsa, from tropical positions. Lahiri is the most common in Indian practice, but several variants exist, and they disagree by enough to occasionally nudge the Moon across a nakshatra boundary. If your dasha output disagrees with another tool, check the ayanamsa before suspecting a bug — it is the single most frequent cause of legitimate divergence between two correct implementations.

Where Vimshottari fits among the systems

Vedika serves three astrological systems through one API — Vedic (sidereal), Western (tropical), and KP — plus Jaimini, Tajaka, Lal Kitab, and numerology. Vimshottari belongs to the Vedic and KP worlds; KP in particular leans heavily on dasha periods combined with sub-lords for timing.

Honest comparison matters here. Established providers such as Prokerala (around $19/mo), AstrologyAPI.com (around $29/mo), and RoxyAPI (around $39/mo) all offer solid dasha endpoints and have mature catalogues. Vedika's differentiators are specific rather than vague: the open-source ephemeris engine you can audit yourself, an interpretation layer that cites classical texts, output in 30 languages including 14 Indic ones, and a public Model Context Protocol server (npx @vedika-io/mcp-server) that lets an MCP-compatible client or LLM agent call dasha and chart tools directly. Pricing starts at $12/mo for Starter and scales to $240/mo for Enterprise, with per-query costs of roughly $0.01-$0.05. Full tiers are on the pricing page.

Key facts

• Vimshottari Dasha is a 120-year cycle split among nine grahas: Ketu 7, Venus 20, Sun 6, Moon 10, Mars 7, Rahu 18, Jupiter 16, Saturn 19, Mercury 17.
• The starting period and its balance are set by the Moon's nakshatra at birth, so birth time, location, and timezone all materially affect the result.
• Periods nest: Mahadasha > Antardasha > Pratyantardasha > Sookshma > Prana, each allotted proportionally from its parent.
• Compute structured periods via /v2/astrology/*; get a grounded reading via POST /api/v1/astrology/query (SSE streaming available).
• Auth uses x-api-key: vk_live_* against https://api.vedika.io; a free sandbox needs no key.
• Positions come from the open-source XALEN Ephemeris, validated against JPL DE440 and swetest with no chart beyond 0.1° — an astronomical precision claim, not a prediction guarantee.
• Ayanamsa choice (commonly Lahiri) is the usual reason two correct dasha implementations disagree.

Getting started

The fastest path is to prototype against the free sandbox, confirm the period shapes match your UI, then swap in a live key. The full request and response schemas, including deeper sub-period parameters, live in the API docs. If you are weighing which timing systems to expose to users, the same chart data also drives transit and other dasha variants, so you can layer them without re-ingesting birth data.