Vimshottari Mahadasha

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

Returns the 9 Mahadasha periods of the 120-year Vimshottari cycle, plus Moon nakshatra info, dasha balance at birth, and the currently running dasha at all 5 levels (MD → AD → PD → SD → Pran).

This is the starting point of the Vimshottari lazy-load chain. Sub-periods are fetched on demand via separate endpoints — keeping the initial payload under 3 KB.

Lazy-load chain
vimshottari-mahadasha → antardasha → pratyantardasha → sookshma → pran

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`.
`reference_date`	string	No	`YYYY-MM-DD`. Compute “current dasha” as of this date.

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

Field	Type	Description
`name`	string	Nakshatra name.
`number`	integer	1–27.
`lord`	string	Nakshatra lord (first Mahadasha planet).
`degree_in_nakshatra`	number	Moon’s degree within the nakshatra (0–13.33).
`percentage_traversed`	number	Determines dasha balance.

current_dasha

Always returns all 5 levels regardless of this being an MD-only endpoint.

Field	Type	Description
`mahadasha`	object	`planet`, `start_date`, `end_date`, `remaining`.
`antardasha`	object	Same fields.
`pratyantardasha`	object	Same fields.
`sookshma_dasha`	object	Same fields (datetime format).
`pran_dasha`	object	Same fields (datetime format).
`summary`	string	e.g. `Ketu-Mercury-Sun-Mars-Saturn`

mahadasha_table

9 Mahadasha entries covering the full 120-year cycle. No nested sub-periods.

Field	Type	Description
`planet`	string	Dasha lord.
`years`	integer	Full period duration in years.
`start_date`	string	`YYYY-MM-DD`.
`end_date`	string	`YYYY-MM-DD`.
`is_balance`	boolean	`true` for the first (balance) period.
`is_current`	boolean	`true` for the currently active Mahadasha.

The 9 Dasha Lords

Planet	Years
Ketu	7
Venus	20
Sun	6
Moon	10
Mars	7
Rahu	18
Jupiter	16
Saturn	19
Mercury	17

Total cycle: 120 years.

Next step: Antardasha

To see the 9 sub-periods within a Mahadasha, pass the planet value from the tapped row to the Antardasha endpoint.

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`	`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-mahadasha" \
  -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-mahadasha',
  {
    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-mahadasha',
    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-mahadasha');
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-mahadasha'),
    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-mahadasha"
    )!)
    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-mahadasha")
        .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-mahadasha",
        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-mahadasha')
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)",
    "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 13d 10h"
      },
      "antardasha": {
        "planet": "Mercury",
        "start_date": "2026-02-09",
        "end_date": "2027-02-07",
        "remaining": "7m 13d 10h"
      },
      "pratyantardasha": {
        "planet": "Sun",
        "start_date": "2026-06-22",
        "end_date": "2026-07-10",
        "remaining": "15d 5h 25min"
      },
      "sookshma_dasha": {
        "planet": "Mars",
        "start_date": "2026-06-25 05:04",
        "end_date": "2026-06-26 06:26",
        "remaining": "14h 4min"
      },
      "pran_dasha": {
        "planet": "Saturn",
        "start_date": "2026-06-25 13:44",
        "end_date": "2026-06-25 17:45",
        "remaining": "1h 24min"
      },
      "summary": "Ketu-Mercury-Sun-Mars-Saturn"
    },
    "mahadasha_table": [
      {
        "planet": "Saturn",
        "years": 19,
        "start_date": "1990-05-20",
        "end_date": "2003-02-07",
        "is_balance": true,
        "is_current": false
      },
      {
        "planet": "Mercury",
        "years": 17,
        "start_date": "2003-02-07",
        "end_date": "2020-02-07",
        "is_balance": false,
        "is_current": false
      },
      {
        "planet": "Ketu",
        "years": 7,
        "start_date": "2020-02-07",
        "end_date": "2027-02-07",
        "is_balance": false,
        "is_current": true
      }
    ]
  },
  "meta": {
    "endpoint": "/api/v3/vedic/dashas/vimshottari-mahadasha",
    "version": "3.0",
    "response_time_ms": 3,
    "timestamp": "2026-06-25T16:21:20+05:30",
    "credits_remaining": 195616,
    "request_id": "f6abb68e466d7299",
    "ayanamsa": {
      "name": "Lahiri",
      "value": 23.725957,
      "value_dms": "23°43'33\""
    },
    "node_type": "mean"
  }
}