POST · VEDIC

Ayanamsa

Endpoint POST https://starsapi.com/api/v3/vedic/ayanamsa

Overview

Resolves one or more ayanamsa values for a given birth moment. The ayanamsa is the angular difference between the tropical and sidereal zodiacs and varies by system and date. This endpoint computes the precise degree(s) you need without performing any chart calculations.

Three modes of operation, controlled by the optional ayanamsa parameter:

Mode	`ayanamsa` param	Response shape
Default	omitted	Returns both defaults: `lahiri` + `kp_old` as a keyed object.
Single	`lahiri`	Flat object (single ayanamsa result, not wrapped in a key).
Multi	`lahiri,kp_old,raman`	Keyed object (one entry per requested key). Maximum 10 keys.

Recommended app flow: on form submit, fire /birth-details + /ayanamsa (no param) in parallel. Vedic screens use the lahiri value; KP screens use kp_old. If a user changes ayanamsa via a settings sheet, re-call this endpoint with the specific key and trigger a lazy recalculation of compute endpoints.

Authentication

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

Request body

Field	Type	Required	Description
`year`	integer	Yes	Birth year (e.g. 1990)
`month`	integer	Yes	Birth month (1–12)
`day`	integer	Yes	Birth day (1–31)
`hour`	integer	Yes	Birth hour (0–23)
`minute`	integer	Yes	Birth minute (0–59)
`second`	integer	No	Birth second (0–59). Defaults to `0`.
`timezone`	string	Yes	IANA timezone identifier (e.g. `Asia/Kolkata`).
`latitude`	number	Yes	Signed decimal latitude.
`longitude`	number	Yes	Signed decimal longitude.
`ayanamsa`	string	No	Ayanamsa key or comma-separated keys (max 10). Omit for both defaults (`lahiri` + `kp_old`). See supported keys.
`node_type`	string	No	`true` or `mean`. Controls Rahu/Ketu node position used internally. Defaults to `mean`.

Response modes

Default mode (no `ayanamsa` param)

Returns both platform defaults as a keyed object:

{
  "data": {
    "ayanamsa": {
      "lahiri": {
        "key": "lahiri",
        "name": "Lahiri (Chitrapaksha)",
        "value": 23.72459,
        "value_dms": "23°43'28\""
      },
      "kp_old": {
        "key": "kp_old",
        "name": "KP Old (Krishnamurti)",
        "value": 23.71832,
        "value_dms": "23°43'06\""
      }
    }
  }
}

Single mode (`ayanamsa=lahiri`)

Returns a flat object — no outer key wrapper:

{
  "data": {
    "ayanamsa": {
      "key": "lahiri",
      "name": "Lahiri (Chitrapaksha)",
      "value": 23.72459,
      "value_dms": "23°43'28\""
    }
  }
}

Multi mode (`ayanamsa=lahiri,kp_old,raman`)

Returns a keyed object with one entry per requested key:

{
  "data": {
    "ayanamsa": {
      "lahiri": {
        "key": "lahiri",
        "name": "Lahiri (Chitrapaksha)",
        "value": 23.72459,
        "value_dms": "23°43'28\""
      },
      "kp_old": {
        "key": "kp_old",
        "name": "KP Old (Krishnamurti)",
        "value": 23.71832,
        "value_dms": "23°43'06\""
      },
      "raman": {
        "key": "raman",
        "name": "Raman",
        "value": 22.37610,
        "value_dms": "22°22'34\""
      }
    }
  }
}

Per-ayanamsa fields

Field	Type	Description
`key`	string	Machine-readable ayanamsa identifier (same as the request key).
`name`	string	Human-readable display name.
`value`	number	Ayanamsa in decimal degrees at the birth moment.
`value_dms`	string	Ayanamsa in degrees–minutes–seconds notation.

The meta block includes node_type (true or mean) but no ayanamsa sub-block — the ayanamsa data is the response itself.

Supported ayanamsa keys

All 47 unique keys from EphemerisService are accepted. The four aliases (lahiri_chitrapaksha → lahiri, etc.) resolve silently to their canonical key. Sending an unknown key returns INVALID_AYANAMSA.

Full key list (click to expand)

lahiri
kp_old
raman
krishnamurti
kp_new
yukteshwar
jn_bhasin
bv_raman
true_chitrapaksha
suryasiddhanta
suryasiddhanta_msun
aryabhata
aryabhata_msun
ss_revati
ss_citra
djwhal_khul
sassanian
ushashashi
hipparchos
galactic_center_0_sag
fagan_bradley
galactic_center_brand
galactic_center_gilbrand
galactic_center_mittalaql
galactic_center_cochrane
galactic_center_mula
galactic_equator_iau1958
galactic_equator_true
galactic_equator_mula
skydram_aldebaran_15tau
aldebaran_15tau
hipparchos_sidtime
sassanian_sidtime
tropical
de_luce
usha_shashi_new
sundara_rajan
valensmoon
lahiri_1940
lahiri_vpnath
krishnamurti_senthil
pushya_paksha
mandi_point
true_pushya
true_mula
true_revati
galactic_ayan_u_0_sag

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	A required field is absent.
400	`INVALID_DATE`	Year/month/day combination does not resolve to a real date.
400	`INVALID_TIME`	Hour/minute/second outside valid range.
400	`INVALID_TIMEZONE`	Timezone string is not a valid IANA identifier.
400	`INVALID_COORDINATE`	Latitude or longitude outside valid range.
400	`INVALID_AYANAMSA`	One or more ayanamsa keys not recognized.
400	`TOO_MANY_AYANAMSAS`	More than 10 comma-separated keys.
400	`INVALID_JSON`	Request body is not valid JSON.
401	`UNAUTHORIZED`	Missing or invalid API key.
405	`METHOD_NOT_ALLOWED`	Request method is not POST.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/vedic/ayanamsa" \
  -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/ayanamsa',
  {
    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/ayanamsa',
    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/ayanamsa');
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/ayanamsa'),
    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/ayanamsa"
    )!)
    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/ayanamsa")
        .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/ayanamsa",
        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/ayanamsa')
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": {
    "ayanamsa": {
      "lahiri": {
        "key": "lahiri",
        "name": "Lahiri (Chitrapaksha)",
        "value": 23.72459,
        "value_dms": "23°43'28\""
      },
      "kp_old": {
        "key": "kp_old",
        "name": "KP Old (Krishnamurti)",
        "value": 23.71832,
        "value_dms": "23°43'06\""
      }
    }
  },
  "meta": {
    "endpoint": "/api/v3/vedic/ayanamsa",
    "request_id": "a1b2c3d4e5f6g7h8",
    "node_type": "mean"
  }
}