Docs
Vedic Astrology
Natal
Natal Basics

POST · VEDIC

Natal Basics

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

Returns the foundational Vedic chart profile for a birth event — Lagna, Moon sign, Sun sign, birth nakshatra, and the complete Panchang snapshot (tithi, yoga, karana, vaar, paksha) along with precise time-correction data (sunrise, GMT, DST, LMT, ishtakal) and Hindu calendar context (maas, samvatsara, ritu). This is the “birth certificate” of Vedic astrology: everything an astrologer reads before opening the planetary chart.

Tithi and nakshatra are returned both at sunrise and at birth — a critical distinction in Vedic practice, since the astrological day begins at sunrise, not midnight. Bhayat (elapsed nakshatra time) and Bhabhog (total nakshatra duration) are given in ghati-pala and HMS formats for Dasha balance computation.

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 — sunrise computation and Panchang elements depend on the precise time and place of birth.

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 →

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

The response is grouped into logical sections under data. Birth input is not echoed back — call /vedic/birth-details separately for that.

vedic_profile

The four anchor points of a Vedic horoscope at a glance.

Field	Type	Description
vedic_profile.moon_sign
`sign`	string	Moon’s sidereal sign (Rashi) in English.
`sign_hindi`	string	Sign in Hindi.
`sign_number`	integer	1 = Aries … 12 = Pisces.
`degree`	number	Moon’s degree within the sign (0–30).
`degree_dms`	string	Same in D°M′S″ format.
vedic_profile.nakshatra
`name`	string	Birth nakshatra (lunar mansion of the Moon).
`nakshatra_pada`	integer	Pada (quarter), `1`–`4`.
`nakshatra_lord`	string	Vimshottari dasha lord of the nakshatra.
`longitude`	number	Absolute sidereal longitude of the Moon (0–360).
`longitude_dms`	string	Same in D°M′S″ format.
vedic_profile.sun_sign
`sign`	string	Sun’s sidereal sign in English.
`sign_hindi`	string	Sign in Hindi.
`sign_number`	integer	Sign number (1–12).
`degree`	number	Sun’s degree within the sign (0–30).
`degree_dms`	string	Same in D°M′S″ format.
vedic_profile.lagna
`sign`	string	Ascendant (Lagna) sign in English.
`sign_hindi`	string	Lagna sign in Hindi.
`sign_number`	integer	Sign number (1–12).
`degree`	number	Ascendant degree within the sign (0–30).
`degree_dms`	string	Same in D°M′S″ format.

sunrise

Sunrise at the birth location on the birth date. The Vedic day begins at sunrise, not midnight.

Field	Type	Description
`ut_time`	string	Sunrise in Universal Time (HH:MM:SS).
`local_time`	string	Sunrise in local clock time.
`local_datetime`	string	Full local date-time of sunrise.
`timezone`	string	IANA timezone used.
`timezone_offset`	number	UTC offset in hours (e.g. `5.5` for IST).
`sunrise_date`	string	Calendar date of sunrise (YYYY-MM-DD).
`birth_before_sunrise`	boolean	`true` if birth occurred before sunrise — the Vedic day belongs to the previous calendar date.

time_corrections

GMT, DST, and Local Mean Time adjustments applied to the birth time.

Field	Type	Description
`gmt_at_birth`	string	Birth time converted to GMT (HH:MM:SS).
`dst_correction`	string	DST offset applied (e.g. `+00:00:00` if none).
`lmt_correction`	string	Local Mean Time correction from the standard meridian.
`lmt_correction_minutes`	number	Same correction in decimal minutes.
`local_mean_time`	string	Birth time adjusted to Local Mean Time (HH:MM:SS).
`standard_meridian`	string	Standard meridian for the timezone (e.g. `82°30′E` for IST).
`standard_meridian_deg`	number	Same in decimal degrees.

bhayat & bhabhog

Bhayat is the elapsed portion of the birth nakshatra at the time of birth. Bhabhog is the total duration of that nakshatra. Together they determine the Dasha balance at birth — the starting point for all Vimshottari timing.

Field	Type	Description
bhayat (elapsed)
`ghati`	integer	Elapsed ghatis (1 ghati = 24 minutes).
`pala`	integer	Elapsed palas (1 pala = 24 seconds).
`vighati`	number	Elapsed vighatis (sub-pala).
`decimal_ghati`	number	Total elapsed time as decimal ghatis.
`hms`	string	Elapsed time in HH:MM:SS.
`percent_traversed`	number	Percentage of nakshatra completed at birth.
`percent_remaining`	number	Percentage remaining.
`nakshatra_entry`	string	Date-time when Moon entered this nakshatra.
bhabhog (total duration)
`ghati`	integer	Total ghatis for the full nakshatra transit.
`pala`	integer	Total palas.
`vighati`	number	Total vighatis.
`decimal_ghati`	number	Total duration as decimal ghatis.
`hms`	string	Total duration in HH:MM:SS.
`nakshatra_exit`	string	Date-time when Moon exits this nakshatra.

ishtakal

Time elapsed since sunrise to the moment of birth, in Vedic time units.

Field	Type	Description
`ghati`	integer	Elapsed ghatis since sunrise.
`pala`	integer	Elapsed palas.
`vighati`	number	Elapsed vighatis.
`decimal_ghatis`	number	Total as decimal ghatis.
`elapsed_hms`	string	Elapsed time in HH:MM:SS.
`from_sunrise`	string	Sunrise time used as reference (HH:MM:SS).
`measured_from`	string	Which sunrise was used: `same-day sunrise` or `previous-day sunrise`.

Panchang elements

The five limbs of the Panchang at birth, plus vaar (weekday).

Field	Type	Description
tithi (at_sunrise & at_birth)
`tithi_number`	integer	Tithi number in the lunar month (1–30).
`tithi_in_paksha`	integer	Tithi number within the paksha (1–15).
`tithi_name`	string	Tithi name (e.g. `Ekadashi`).
`paksha`	string	`Shukla` (waxing) or `Krishna` (waning).
`paksha_tithi_name`	string	Combined name (e.g. `Krishna Ekadashi`).
`start_ut`	string	Tithi start in Universal Time.
`end_ut`	string	Tithi end in Universal Time.
nakshatra (at_sunrise & at_birth)
`name`	string	Nakshatra name.
`nakshatra_pada`	integer	Pada (1–4).
`nakshatra_lord`	string	Vimshottari lord.
vaar (astrological & western)
`vaar_number`	integer	Day number (0 = Sunday … 6 = Saturday).
`vaar_name`	string	Hindi weekday name (e.g. `Ravivaar`).
`vaar_name_en`	string	English weekday name.
`vaar_lord`	string	Planetary lord of the day.
`birth_before_sunrise`	boolean	If `true`, the astrological vaar differs from the western calendar day.
yoga
`yoga_number`	integer	Yoga number (1–27).
`yoga_name`	string	Yoga name (e.g. `Vishkambha`).
`start_ut` / `end_ut`	string	Yoga start and end in UT.
karana
`karana_number`	integer	Karana number (1–60 in the cycle).
`karana_name`	string	Karana name (e.g. `Bava`).
`half`	string	`First` or `Second` half of the tithi.
`start_ut` / `end_ut`	string	Karana start and end in UT.
paksha
`paksha`	string	Top-level: `Shukla` or `Krishna`.

Hindu calendar

Field	Type	Description
maas
`is_adhika_maas`	boolean	`true` if birth falls in an intercalary (extra) month.
`purnimant.maas_name`	string	Month name in the Purnimant (North Indian) system.
`purnimant.maas_name_hindi`	string	Same in Hindi.
`amant.maas_name`	string	Month name in the Amant (South Indian) system.
`amant.maas_name_hindi`	string	Same in Hindi.
samvatsara
`samvatsara_number`	integer	Position in the 60-year Jupiter cycle (1–60).
`samvatsara_name`	string	Samvatsara name (e.g. `Srimukha`).
`vikram_samvat`	integer	Year in the Vikram Samvat calendar.
`shaka_samvat`	integer	Year in the Shaka Samvat (national) calendar.
ritu
`ritu_number`	integer	Season number (1–6).
`ritu_name`	string	Season name in Sanskrit (e.g. `Vasanta`).
`ritu_name_en`	string	English season name.
`ritu_months`	string[]	The two Hindu months that fall in this season.

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.

Use cases

Birth profile cards — surface Lagna, Moon sign, Sun sign, and birth nakshatra the moment a user enters their details.
Dasha balance — use bhayat and bhabhog to compute the exact Vimshottari starting balance without a second call.
Panchang at birth — display tithi, yoga, karana, and vaar for muhurta analysis or compatibility checks.
Localized calendars — render the birth month in both Purnimant (North) and Amant (South) systems, with Vikram and Shaka year numbers.
Pre-sunrise births — the birth_before_sunrise flag and dual sunrise/birth panchang lets you handle the Vedic day boundary correctly.

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/natal-basics" \
  -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/natal-basics',
  {
    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/natal-basics',
    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/natal-basics');
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/natal-basics'),
    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/natal-basics"
    )!)
    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/natal-basics")
        .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/natal-basics",
        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/natal-basics')
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": {
    "vedic_profile": {
      "moon_sign": {
        "sign": "Pisces",
        "sign_hindi": "Meena",
        "sign_number": 12,
        "degree": 7.74,
        "degree_dms": "07°44'28\""
      },
      "nakshatra": {
        "name": "Uttara Bhadrapada",
        "nakshatra_pada": 2,
        "nakshatra_lord": "Saturn",
        "longitude": 337.74,
        "longitude_dms": "337°44'28\""
      },
      "sun_sign": {
        "sign": "Taurus",
        "sign_hindi": "Vrishabha",
        "sign_number": 2,
        "degree": 5.37,
        "degree_dms": "05°22'00\""
      },
      "lagna": {
        "sign": "Virgo",
        "sign_hindi": "Kanya",
        "sign_number": 6,
        "degree": 6.25,
        "degree_dms": "06°14'52\""
      }
    },
    "sunrise": {
      "ut_time": "23:58:02",
      "local_time": "05:28:02",
      "local_datetime": "1990-05-20 05:28:02",
      "timezone": "Asia/Kolkata",
      "timezone_offset": 5.5,
      "sunrise_date": "1990-05-20",
      "birth_before_sunrise": false
    },
    "time_corrections": {
      "gmt_at_birth": "09:00:00",
      "dst_correction": "+00:00:00",
      "lmt_correction": "-00:21:10",
      "lmt_correction_minutes": -21.164,
      "local_mean_time": "14:08:50",
      "standard_meridian": "82°30'E",
      "standard_meridian_deg": 82.5
    },
    "bhayat": {
      "ghati": 18,
      "pala": 40,
      "vighati": 47.5,
      "decimal_ghati": 18.6799,
      "hms": "07:28:19",
      "percent_traversed": 33.4191,
      "percent_remaining": 66.5809,
      "nakshatra_entry": "1990-05-20 07:01:41"
    },
    "bhabhog": {
      "ghati": 55,
      "pala": 53,
      "vighati": 45,
      "decimal_ghati": 55.8958,
      "hms": "22:21:30",
      "nakshatra_exit": "1990-05-21 05:23:11"
    },
    "ishtakal": {
      "ghati": 22,
      "pala": 34,
      "vighati": 55,
      "decimal_ghatis": 22.5819,
      "elapsed_hms": "09:01:58",
      "from_sunrise": "05:28:02",
      "measured_from": "same-day sunrise"
    },
    "tithi": {
      "at_sunrise": {
        "tithi_number": 25,
        "tithi_in_paksha": 10,
        "tithi_name": "Dashami",
        "paksha": "Krishna",
        "paksha_tithi_name": "Krishna Dashami",
        "start_ut": "1990-05-19 06:29:56",
        "end_ut": "1990-05-20 04:41:42"
      },
      "at_birth": {
        "tithi_number": 26,
        "tithi_in_paksha": 11,
        "tithi_name": "Ekadashi",
        "paksha": "Krishna",
        "paksha_tithi_name": "Krishna Ekadashi",
        "start_ut": "1990-05-20 04:41:42",
        "end_ut": "1990-05-21 02:11:02"
      }
    },
    "nakshatra": {
      "at_sunrise": {
        "name": "Purva Bhadrapada",
        "nakshatra_pada": 4,
        "nakshatra_lord": "Jupiter"
      },
      "at_birth": {
        "name": "Uttara Bhadrapada",
        "nakshatra_pada": 2,
        "nakshatra_lord": "Saturn"
      }
    },
    "vaar": {
      "astrological": {
        "vaar_number": 0,
        "vaar_name": "Ravivaar",
        "vaar_name_en": "Sunday",
        "vaar_lord": "Sun",
        "sunrise_date": "1990-05-20"
      },
      "western": {
        "vaar_number": 0,
        "vaar_name": "Ravivaar",
        "vaar_name_en": "Sunday",
        "vaar_lord": "Sun",
        "date": "1990-05-20"
      },
      "birth_before_sunrise": false
    },
    "yoga": {
      "yoga_number": 1,
      "yoga_name": "Vishkambha",
      "start_ut": "1990-05-19 12:00:49",
      "end_ut": "1990-05-20 09:20:44"
    },
    "karana": {
      "karana_number": 51,
      "karana_name": "Bava",
      "half": "First",
      "tithi_number": 26,
      "tithi_name": "Krishna Ekadashi",
      "start_ut": "1990-05-20 04:41:42",
      "end_ut": "1990-05-20 15:31:18"
    },
    "paksha": "Krishna",
    "maas": {
      "is_adhika_maas": false,
      "purnimant": {
        "maas_name": "Jyeshtha",
        "maas_name_hindi": "ज्येष्ठ",
        "paksha": "krishna",
        "system": "Purnimant (North India)"
      },
      "amant": {
        "maas_name": "Vaishakha",
        "maas_name_hindi": "वैशाख",
        "paksha": "krishna",
        "system": "Amant (South India)"
      }
    },
    "samvatsara": {
      "samvatsara_number": 7,
      "samvatsara_name": "Srimukha",
      "vikram_samvat": 2047,
      "shaka_samvat": 2068
    },
    "ritu": {
      "ritu_number": 1,
      "ritu_name": "Vasanta",
      "ritu_name_en": "Spring",
      "ritu_months": ["Chaitra", "Vaishakha"]
    }
  },
  "meta": {
    "endpoint": "/api/v3/vedic/natal/natal-basics",
    "version": "3.0",
    "response_time_ms": 98,
    "timestamp": "2026-06-08T23:34:31+05:30",
    "credits_remaining": 198615,
    "request_id": "04908e0d8075da9b",
    "ayanamsa": {
      "name": "Lahiri",
      "value": 23.725957,
      "value_dms": "23°43'33\""
    }
  }
}