Ascendant

Endpoint POST https://starsapi.com/api/v3/vedic/natal/ascendant

Returns the sidereal Ascendant (Lagna) for a given birth — the rising sign at the exact moment and location of birth. The Ascendant is the most personal point in a Vedic horoscope: it determines the house framework, sets the Dasha starting point, and shapes the native’s physical constitution and outlook.

The response includes the sign (with Hindi name, lord, element, and quality), ecliptic longitude, degree within the sign, nakshatra, nakshatra lord, and pada — everything needed to anchor a chart or power a horoscope UI.

Authentication

Required. Three methods accepted:

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

See authentication for security considerations.

Request body

Send a JSON object with Content-Type: application/json. The core fields are required — the ascendant depends on the precise time and place of birth, so an approximate value in any field shifts the rising sign.

Field	Type	Required	Description
`year`	integer	Yes	Birth year, 4-digit (e.g. `1990`).
`month`	integer	Yes	Birth month, `1`–`12`.
`day`	integer	Yes	Day of month, `1`–`31`.
`hour`	integer	Yes	Hour in 24-hour local clock time, `0`–`23`.
`minute`	integer	Yes	Minute, `0`–`59`.
`second`	integer	No	Second, `0`–`59`. Default `0`. Improves precision — the Ascendant moves ∼1° every 4 minutes.
`latitude`	number	Yes	Signed decimal degrees, −90…90. Positive = North (e.g. `28.6139`).
`longitude`	number	Yes	Signed decimal degrees, −180…180. Positive = East (e.g. `77.2090`).
`timezone`	string	Yes	IANA timezone identifier (e.g. `Asia/Kolkata`, `America/New_York`). DST is resolved automatically.
`name`	string	No	Native’s name. Not returned by this endpoint; use `/vedic/birth-details` to retrieve it.
`place`	string	No	Birth place label. Not returned by this endpoint; use `/vedic/birth-details` to retrieve it.
`ayanamsa`	string	No	Sidereal mode. Default `lahiri`. Popular: `lahiri`, `raman`, `kp`, `kp_new`, `kp_senthil`, `fagan_bradley`, `yukteshwar`. Full list of 45+ ayanamsas →

Use the local clock time of birth. Pass the wall-clock time as recorded on the birth certificate together with the IANA timezone of the birth place — the backend converts to UTC internally. Do not pre-convert to UTC yourself.

Response shape

A successful response carries a top-level status + success flag, a data.ascendant object, and a meta envelope with request metadata. Birth input (name, date, time, gender, location) is not echoed back — call /vedic/birth-details separately to retrieve resolved birth details.

Field	Type	Description
`status`	integer	HTTP status code echo (200 on success).
`success`	boolean	Always `true` on success.
data.ascendant
`sign`	string	Rising sign in English (e.g. `Virgo`).
`sign_hindi`	string	Hindi / Sanskrit name (e.g. `Kanya`).
`sign_number`	integer	Sign number, 1 = Aries … 12 = Pisces.
`sign_lord`	string	Ruling planet of the rising sign — the chart lord.
`element`	string	Element (tattva): `Fire`, `Earth`, `Air`, or `Water`.
`quality`	string	Modality: `Movable` (Cardinal), `Fixed`, or `Dual` (Mutable).
`longitude`	number	Absolute sidereal ecliptic longitude in decimal degrees (0–360).
`longitude_dms`	string	Same longitude in D°M′S″ format.
`degree_in_sign`	number	Degree within the sign (0–30).
`degree_in_sign_dms`	string	Same in D°M′S″ format.
`nakshatra`	string	Lunar mansion the Ascendant falls in.
`nakshatra_lord`	string	Vimshottari lord of the nakshatra.
`nakshatra_pada`	integer	Quarter within the nakshatra (`1`–`4`).
meta
`meta.endpoint`	string	Echo of the called endpoint path.
`meta.version`	string	API version (currently `3.0`).
`meta.response_time_ms`	integer	Server-side response time in milliseconds.
`meta.timestamp`	string (ISO 8601)	Time the response was served.
`meta.credits_remaining`	integer	API credits remaining on your plan.
`meta.request_id`	string	Unique request identifier — include in support tickets.
`meta.ayanamsa.name`	string	Name of the sidereal mode applied (e.g. `Lahiri`).
`meta.ayanamsa.value`	number	Ayanamsa offset in decimal degrees.
`meta.ayanamsa.value_dms`	string	Same in D°M′S″ format.

Use cases

Chart casting — the ascendant fixes house 1; pair it with the planetary-positions endpoint to assemble a full Lagna chart.
Onboarding — surface a user’s rising sign and chart lord the moment they enter birth details, before computing anything heavier.
Personality summaries — combine sign, sign_lord, and nakshatra for a rising-sign profile card.
Localized UI — the dual English / Hindi fields let you render the same response in either language without a second call.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	A required birth field is absent.
400	`INVALID_DATE`	Invalid calendar date.
400	`INVALID_TIME`	Hour/minute/second out of range.
400	`INVALID_TIMEZONE`	Numeric or non-IANA timezone.
400	`INVALID_COORDINATE`	`latitude` / `longitude` out of range.
401	`AUTH_MISSING_KEY`	No API key in request.
401	`AUTH_INVALID_KEY`	Key format invalid or not found.
401	`AUTH_REVOKED_KEY`	Key has been revoked.
403	`AUTH_ORIGIN_DENIED`	Request from non-whitelisted origin.
405	`METHOD_NOT_ALLOWED`	Non-POST request.
429	`RATE_LIMIT_EXCEEDED`	Plan quota exceeded.
500	`CALCULATION_ERROR`	Ephemeris calculation failed.

Error response format

{
  "success": false,
  "error": {
    "code": "INVALID_TIMEZONE",
    "message": "Unrecognised timezone: 'Asia/Calcutta_'. Use a valid IANA identifier such as 'Asia/Kolkata'."
  }
}

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/vedic/natal/ascendant" \
  -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/natal/ascendant',
  {
    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/natal/ascendant',
    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/natal/ascendant');
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/natal/ascendant'),
    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/natal/ascendant"
    )!)
    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/natal/ascendant")
        .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/natal/ascendant",
        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/natal/ascendant')
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": {
    "ascendant": {
      "sign": "Virgo",
      "sign_hindi": "Kanya",
      "sign_number": 6,
      "sign_lord": "Mercury",
      "element": "Earth",
      "quality": "Dual",
      "longitude": 156.2478,
      "longitude_dms": "156°14'52\"",
      "degree_in_sign": 6.2478,
      "degree_in_sign_dms": "6°14'52\"",
      "nakshatra": "Uttara Phalguni",
      "nakshatra_lord": "Sun",
      "nakshatra_pada": 3
    }
  },
  "meta": {
    "endpoint": "/api/v3/vedic/natal/ascendant",
    "version": "3.0",
    "response_time_ms": 29,
    "timestamp": "2026-06-08T17:46:16+05:30",
    "credits_remaining": 198646,
    "request_id": "80847fb1080d4c92",
    "ayanamsa": {
      "name": "Lahiri",
      "value": 23.725957,
      "value_dms": "23°43'33\""
    }
  }
}