Planets

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

Returns the Ascendant and all 9 Vedic grahas (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu) with baseline positional data: sign, house, longitude, degree within sign, nakshatra, speed, dignity, house lordship, retrograde and combustion status, and baladi avastha.

This is the workhorse endpoint for rendering Vedic birth charts (North or South Indian style) and powering most analytical features. For outer planets (Uranus, Neptune, Pluto, Chiron), use /natal/planets-extended. For KP sub-lords, functional nature, divisional charts, and full 4-fold avasthas, use /natal/planets-advanced.

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. All core fields are required.

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`.
`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`). 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`. Full list of 45+ ayanamsas →
`node_type`	string	No	`mean` (default) or `true`. Controls Rahu/Ketu position calculation.

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

Returns data.ascendant (the Lagna) and data.planets (array of 9 grahas). The response sample shows 3 representative planets — all 9 follow the same shape. Birth input is not echoed back — call /vedic/birth-details separately.

Ascendant fields

Field	Type	Description
`longitude`	number	Absolute sidereal ecliptic longitude (0–360).
`longitude_dms`	string	Same in D°M′S″ format.
`sign_number`	integer	1 = Aries … 12 = Pisces.
`sign`	string	Sign name in English.
`sign_hindi`	string	Sign name in Hindi.
`sign_lord`	string	Ruling planet of the rising sign.
`degree`	number	Degree within the sign (0–30).
`degree_dms`	string	Same in D°M′S″ format.
`nakshatra`	string	Rising nakshatra.
`nakshatra_number`	integer	1 = Ashwini … 27 = Revati.
`nakshatra_lord`	string	Vimshottari lord of the nakshatra.
`nakshatra_pada`	integer	Pada (1–4).
`house`	integer	Always `1`.

Planet fields (per planet)

Field	Type	Description
Identity
`planet`	string	Planet name (e.g. `Sun`, `Rahu`).
`planet_short`	string	Two-letter abbreviation (e.g. `Su`, `Ra`). Useful for table UIs.
`house`	integer	House the planet occupies (1–12).
Sign
`sign_number`	integer	1 = Aries … 12 = Pisces.
`sign`	string	English sign name.
`sign_hindi`	string	Hindi sign name.
`sign_lord`	string	Ruling planet of the sign.
Degrees
`longitude`	number	Absolute sidereal ecliptic longitude (0–360).
`longitude_dms`	string	Same in D°M′S″ format.
`degree`	number	Degree within the sign (0–30).
`degree_dms`	string	Same in D°M′S″ format.
`speed_deg_per_day`	number	Daily motion in degrees. Negative = retrograde.
Nakshatra
`nakshatra`	string	Nakshatra name.
`nakshatra_number`	integer	1 = Ashwini … 27 = Revati.
`nakshatra_lord`	string	Vimshottari lord.
`nakshatra_pada`	integer	Pada (1–4).
Status
`dignity`	string	`exalted`, `own_sign`, `moolatrikona`, `friend`, `neutral`, `enemy`, or `debilitated`.
`house_lordship`	integer[]	Houses this planet rules for this ascendant (e.g. `[4, 9]`). Empty for Rahu/Ketu.
`is_retrograde`	boolean	`true` if retrograde. Rahu/Ketu are always retrograde.
`is_combust`	boolean	`true` if too close to the Sun.
`baladi_avastha`	string	Age-based state: `Bala` (Infant), `Kumara` (Youth), `Yuva` (Adult), `Vriddha` (Old), or `Mrita` (Dead).

Field	Type	Description
`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	Sidereal mode applied.
`meta.ayanamsa.value`	number	Ayanamsa offset in decimal degrees.
`meta.ayanamsa.value_dms`	string	Same in D°M′S″ format.
`meta.node_type`	string	Rahu/Ketu calculation mode: `mean` or `true`.

Use cases

Birth chart rendering — loop the 9 planets and place them in their houses for a North or South Indian chart.
Dignity table — display each planet’s dignity, house lordship, and retrograde status at a glance.
Dasha context — pair nakshatra lord and sign lord with dasha endpoints to understand period significations.
Combustion alerts — flag combust planets that may underperform in their house.
Compact chart tables — use planet_short for space-efficient grid and table UIs.

Endpoint	Planets	Extra fields
`planets` (this)	9 Vedic grahas	Baseline: position, dignity, lordship, retrograde, combustion, baladi avastha.
`planets-extended`	9 + Uranus, Neptune, Pluto, Chiron	Same baseline fields, adds 4 outer planets.
`planets-advanced`	9 Vedic grahas	Adds KP sub-lords, functional nature, dignity booleans, navamsa, vargottama, full 4-fold avasthas.

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/planets" \
  -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/planets',
  {
    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/planets',
    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/planets');
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/planets'),
    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/planets"
    )!)
    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/planets")
        .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/planets",
        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/planets')
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": {
      "longitude": 156.2478,
      "longitude_dms": "156°14'52\"",
      "sign_number": 6,
      "sign": "Virgo",
      "sign_hindi": "Kanya",
      "sign_lord": "Mercury",
      "degree": 6.2478,
      "degree_dms": "06°14'52\"",
      "nakshatra": "Uttara Phalguni",
      "nakshatra_number": 12,
      "nakshatra_lord": "Sun",
      "nakshatra_pada": 3,
      "house": 1
    },
    "planets": [
      {
        "planet": "Sun",
        "planet_short": "Su",
        "house": 9,
        "sign_number": 2,
        "sign": "Taurus",
        "sign_hindi": "Vrishabha",
        "sign_lord": "Venus",
        "longitude": 35.3668,
        "longitude_dms": "35°22'00\"",
        "degree": 5.3668,
        "degree_dms": "05°22'00\"",
        "speed_deg_per_day": 0.962625,
        "nakshatra": "Krittika",
        "nakshatra_number": 3,
        "nakshatra_lord": "Sun",
        "nakshatra_pada": 3,
        "dignity": "neutral",
        "house_lordship": [12],
        "is_retrograde": false,
        "is_combust": false,
        "baladi_avastha": "Mrita"
      },
      {
        "planet": "Venus",
        "planet_short": "Ve",
        "house": 7,
        "sign_number": 12,
        "sign": "Pisces",
        "sign_hindi": "Meena",
        "sign_lord": "Jupiter",
        "longitude": 354.6714,
        "longitude_dms": "354°40'17\"",
        "degree": 24.6714,
        "degree_dms": "24°40'17\"",
        "speed_deg_per_day": 1.148018,
        "nakshatra": "Revati",
        "nakshatra_number": 27,
        "nakshatra_lord": "Mercury",
        "nakshatra_pada": 3,
        "dignity": "exalted",
        "house_lordship": [2, 9],
        "is_retrograde": false,
        "is_combust": false,
        "baladi_avastha": "Bala"
      },
      {
        "planet": "Saturn",
        "planet_short": "Sa",
        "house": 5,
        "sign_number": 10,
        "sign": "Capricorn",
        "sign_hindi": "Makara",
        "sign_lord": "Saturn",
        "longitude": 271.4223,
        "longitude_dms": "271°25'20\"",
        "degree": 1.4223,
        "degree_dms": "01°25'20\"",
        "speed_deg_per_day": -0.02457,
        "nakshatra": "Uttara Ashadha",
        "nakshatra_number": 21,
        "nakshatra_lord": "Sun",
        "nakshatra_pada": 2,
        "dignity": "own_sign",
        "house_lordship": [5, 6],
        "is_retrograde": true,
        "is_combust": false,
        "baladi_avastha": "Mrita"
      }
    ],
    "total_planets": 9
  },
  "meta": {
    "endpoint": "/api/v3/vedic/natal/planets",
    "version": "3.0",
    "response_time_ms": 5,
    "timestamp": "2026-06-09T06:08:12+05:30",
    "credits_remaining": 198602,
    "request_id": "43b3005aa5c15ccf",
    "ayanamsa": {
      "name": "Lahiri",
      "value": 23.725957,
      "value_dms": "23°43'33\""
    },
    "node_type": "mean"
  }
}