Vimshottari Dasha

Endpoint POST https://starsapi.com/api/v3/vedic/dashas/vimshottari

Returns the complete Vimshottari Dasha (120-year Parashari planetary period system) with three levels of sub-periods: Mahadasha → Antardasha → Pratyantardasha. Includes the dasha balance at birth, the currently running dasha down to Pran level, and the full Mahadasha table with nested sub-periods.

The Vimshottari system is the most widely used dasha system in Vedic astrology. The starting planet is determined by the Moon’s nakshatra at birth, and the balance of the first dasha is proportional to the Moon’s traversal within that nakshatra.

One call, all levels. Unlike APIs that split Vimshottari into separate endpoints for each sub-period level (major, sub, sub-sub, etc.), StarsAPI returns the full dasha tree in a single call. Use the levels parameter to control depth (1–5) — no need to chain multiple requests or pass parent period IDs.

Authentication

Method	Example
Header (recommended)	`X-Api-Key: sa_live_xxxxxxxxxxxx`
Bearer	`Authorization: Bearer sa_live_xxxxxxxxxxxx`
Query	`?api_key=sa_live_xxxxxxxxxxxx`

Request body

Field	Type	Required	Description
`year`	integer	Yes	Birth year, 4-digit.
`month`	integer	Yes	Birth month, `1`–`12`.
`day`	integer	Yes	Day of month.
`hour`	integer	Yes	Hour, 24-hour format.
`minute`	integer	Yes	Minute.
`second`	integer	No	Default `0`.
`latitude`	number	Yes	Decimal degrees, −90…90.
`longitude`	number	Yes	Decimal degrees, −180…180.
`timezone`	string	Yes	IANA timezone identifier.
`ayanamsa`	string	No	Default `lahiri`. Full list →
`node_type`	string	No	`mean` (default) or `true`.
`levels`	integer	No	Depth of sub-periods to return, `1`–`5`. Default `3`. Level 1 = Mahadasha only, 2 = +Antardasha, 3 = +Pratyantardasha, 4 = +Sookshma, 5 = +Pran.
`reference_date`	string	No	`YYYY-MM-DD`. Compute “current dasha” as of this date instead of today. Useful for past/future analysis.

Ayanamsa & KP usage

Vimshottari periods are derived from the Moon’s nakshatra position, which shifts with the chosen ayanamsa. Lahiri and Krishnamurti (KP) differ by roughly 5–6 arc-minutes — enough to shift dasha start/end dates by several days, and at deeper levels (Sookshma/Pran) even change the running lord. KP practitioners should pass "ayanamsa": "krishnamurti" (alias kp); variants kp_new and kp_senthil are also supported. The ayanamsa actually used is echoed in the response meta for verification. Unknown ayanamsa names return an error rather than silently falling back to Lahiri.

Response shape

moon_nakshatra

The natal Moon’s nakshatra that determines the starting dasha planet.

Field	Type	Description
`name`	string	Nakshatra name.
`number`	integer	Nakshatra number, 1–27.
`lord`	string	Nakshatra ruling planet (first Mahadasha lord).
`degree_in_nakshatra`	number	Moon’s degree within the nakshatra (0–13.33).
`percentage_traversed`	number	Percentage of nakshatra the Moon has crossed — determines dasha balance.

dasha_at_birth

The dasha running at the exact moment of birth, with balance remaining.

Field	Type	Description
`balance`	string	Human-readable balance of the first Mahadasha.
`running`	string	Compact dasha chain at birth (e.g. `Sat-Ketu-Rahu-Ven-Rahu`).
`details`	object	Broken out: `mahadasha`, `antardasha`, `pratyantardasha`, `sookshma_dasha`, `pran_dasha`.

current_dasha

The dasha running right now, computed at the time of the API call.

Field	Type	Description
`mahadasha`	object	Current Mahadasha: `planet`, `start_date`, `end_date`, `remaining`.
`antardasha`	object	Current Antardasha (same fields).
`pratyantardasha`	object	Current Pratyantardasha.
`sookshma_dasha`	object	Current Sookshma dasha.
`pran_dasha`	object	Current Pran dasha (finest level).
`summary`	string	Compact chain (e.g. `Ketu-Mercury-Venus-Saturn-Jupiter`).

mahadasha_table

Full lifecycle table — an array covering the entire 120-year Vimshottari cycle from birth. Each Mahadasha contains nested antardashas, each of which contains nested pratyantardashas (3 levels deep).

Field	Type	Description
`planet`	string	Dasha lord.
`years`	integer	Full period duration in years.
`start_date`	string	Period start (YYYY-MM-DD).
`end_date`	string	Period end.
`is_balance`	boolean	`true` if this is the first (balance) period.
`duration_days`	number	Exact duration in days (sub-periods).
`antardashas`	array	Nested sub-periods (same shape, with `pratyantardashas` inside).

Use cases

Dasha timeline — render a full lifetime dasha timeline from birth to 120 years.
Current period display — show the user which Mahadasha/Antardasha/Pratyantardasha is running right now.
Prediction engine — feed current dasha lords into your AI or rule-based prediction system.
Dasha balance — show the starting dasha and remaining balance at birth for consultation apps.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	Required field absent.
400	`INVALID_DATE`	Bad calendar date.
400	`INVALID_TIME`	Hour/minute/second out of range.
400	`INVALID_TIMEZONE`	Non-IANA timezone.
400	`INVALID_COORDINATE`	Lat/lon out of range.
400	`INVALID_PARAM`	`levels` not 1–5, or `reference_date` not YYYY-MM-DD.
405	`METHOD_NOT_ALLOWED`	Non-POST request.
500	`COMPUTE_ERROR`	Unknown `ayanamsa` name.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/vedic/dashas/vimshottari" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata"
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/vedic/dashas/vimshottari',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      year: 1990,
      month: 5,
      day: 20,
      hour: 14,
      minute: 30,
      second: 0,
      latitude: 28.6139,
      longitude: 77.209,
      timezone: 'Asia/Kolkata'
    })
  }
);
const result = await response.json();

if (result.success) {
  console.log(result.data);
}

import requests
import os

response = requests.post(
    'https://starsapi.com/api/v3/vedic/dashas/vimshottari',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    json={
        'year': 1990,
        'month': 5,
        'day': 20,
        'hour': 14,
        'minute': 30,
        'second': 0,
        'latitude': 28.6139,
        'longitude': 77.209,
        'timezone': 'Asia/Kolkata'
    }
)
result = response.json()

if result['success']:
    print(result['data'])

<?php
$payload = [
    'year' => 1990,
    'month' => 5,
    'day' => 20,
    'hour' => 14,
    'minute' => 30,
    'second' => 0,
    'latitude' => 28.6139,
    'longitude' => 77.209,
    'timezone' => 'Asia/Kolkata',
];

$ch = curl_init('https://starsapi.com/api/v3/vedic/dashas/vimshottari');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . getenv('STARSAPI_KEY'),
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success']) {
    print_r($data['data']);
}

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<Map<String, dynamic>> getAscendant() async {
  final response = await http.post(
    Uri.parse('https://starsapi.com/api/v3/vedic/dashas/vimshottari'),
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'year': 1990,
      'month': 5,
      'day': 20,
      'hour': 14,
      'minute': 30,
      'second': 0,
      'latitude': 28.6139,
      'longitude': 77.209,
      'timezone': 'Asia/Kolkata',
    }),
  );
  return jsonDecode(response.body);
}

import Foundation

func getAscendant() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/vedic/dashas/vimshottari"
    )!)
    request.httpMethod = "POST"
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = """
        {
            "year": 1990,
            "month": 5,
            "day": 20,
            "hour": 14,
            "minute": 30,
            "second": 0,
            "latitude": 28.6139,
            "longitude": 77.209,
            "timezone": "Asia/Kolkata"
        }
        """.data(using: .utf8)

    let (data, _) = try await URLSession.shared.data(for: request)
    return try JSONSerialization.jsonObject(with: data) as! [String: Any]
}

import okhttp3.*
import org.json.JSONObject

val client = OkHttpClient()
val JSON = "application/json; charset=utf-8".toMediaType()

fun getAscendant(callback: (JSONObject) -> Unit) {
    val payload = """
    {
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata"
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/vedic/dashas/vimshottari")
        .addHeader("X-Api-Key", "YOUR_API_KEY")
        .post(payload.toRequestBody(JSON))
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onResponse(call: Call, response: Response) {
            callback(JSONObject(response.body!!.string()))
        }
        override fun onFailure(call: Call, e: java.io.IOException) {
            e.printStackTrace()
        }
    })
}

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    payload, _ := json.Marshal(map[string]interface{}{
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/vedic/dashas/vimshottari",
        bytes.NewBuffer(payload))
    req.Header.Set("X-Api-Key", os.Getenv("STARSAPI_KEY"))
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result["data"])
}

require 'net/http'
require 'json'

uri = URI('https://starsapi.com/api/v3/vedic/dashas/vimshottari')
payload = {
  'year' => 1990,
  'month' => 5,
  'day' => 20,
  'hour' => 14,
  'minute' => 30,
  'second' => 0,
  'latitude' => 28.6139,
  'longitude' => 77.209,
  'timezone' => 'Asia/Kolkata'
}

req = Net::HTTP::Post.new(uri)
req['X-Api-Key'] = ENV['STARSAPI_KEY']
req['Content-Type'] = 'application/json'
req.body = payload.to_json

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
res = http.request(req)

data = JSON.parse(res.body)
puts data['data'] if data['success']

200 RESPONSE

{
  "status": 200,
  "success": true,
  "data": {
    "dasha_system": "Vimshottari (Parashari)",
    "levels": 3,
    "reference_date": null,
    "moon_nakshatra": {
      "name": "Uttara Bhadrapada",
      "number": 26,
      "lord": "Saturn",
      "degree_in_nakshatra": 4.4078,
      "percentage_traversed": 33.06
    },
    "dasha_at_birth": {
      "balance": "Saturn 12 Years, 8 Months, 19 Days",
      "running": "Sat-Ketu-Rahu-Ven-Rahu",
      "details": {
        "mahadasha": "Saturn",
        "antardasha": "Ketu",
        "pratyantardasha": "Rahu",
        "sookshma_dasha": "Venus",
        "pran_dasha": "Rahu"
      }
    },
    "current_dasha": {
      "mahadasha": {
        "planet": "Ketu",
        "start_date": "2020-02-07",
        "end_date": "2027-02-07",
        "remaining": "7m 29d 13h"
      },
      "antardasha": {
        "planet": "Mercury",
        "start_date": "2026-02-09",
        "end_date": "2027-02-07",
        "remaining": "7m 29d 13h"
      },
      "pratyantardasha": {
        "planet": "Venus",
        "start_date": "2026-04-23",
        "end_date": "2026-06-22",
        "remaining": "13d 5h 3min"
      },
      "sookshma_dasha": {
        "planet": "Saturn",
        "start_date": "2026-06-01",
        "end_date": "2026-06-10",
        "remaining": "1d 3h 18min"
      },
      "pran_dasha": {
        "planet": "Jupiter",
        "start_date": "2026-06-09 10:46",
        "end_date": "2026-06-10 17:21",
        "remaining": "1d 3h 17min"
      },
      "summary": "Ketu-Mercury-Venus-Saturn-Jupiter"
    },
    "mahadasha_table": [
      {
        "planet": "Saturn",
        "years": 19,
        "start_date": "1990-05-20",
        "end_date": "2003-02-07",
        "is_balance": true,
        "antardashas": [
          {
            "planet": "Ketu",
            "start_date": "1990-05-20",
            "end_date": "1990-11-29",
            "duration_days": 192.6,
            "is_balance": true,
            "pratyantardashas": [
              {
                "planet": "Rahu",
                "start_date": "1990-05-20",
                "end_date": "1990-06-06",
                "duration_days": 17.16,
                "is_balance": true
              }
            ]
          }
        ]
      }
    ]
  },
  "meta": {
    "endpoint": "/api/v3/vedic/dashas/vimshottari",
    "version": "3.0",
    "response_time_ms": 12,
    "timestamp": "2026-06-09T07:35:42+05:30",
    "credits_remaining": 198580,
    "request_id": "a1b2c3d4e5f6g7h8",
    "ayanamsa": {
      "name": "Lahiri",
      "value": 23.725957,
      "value_dms": "23°43'33\""
    },
    "node_type": "mean"
  }
}