POST/v1/astro/varshaphal/harsha-bala

Varshaphal — Harsha Bala

Computes Harsha Bala (positional happiness score) for all 7 classical planets in the Varshaphal chart. Maximum = 20 per planet (4 components × 5 points). Harsha Bala measures whether a planet is positionally comfortable in the annual chart — distinct from Pancha Vargeeya Bala which measures mathematical strength. A planet with high Pancha Vargeeya Bala but zero Harsha Bala has the capacity to deliver results but will do so through stress and frustration. Components: Sthana (happy house: Sun 9th, Moon 3rd, Mars 6th, Mercury 1st, Jupiter 11th, Venus 5th, Saturn 12th), Swakshetra/Uccha (own or exaltation sign), Pum-Stri (masculine Sun, Mars, Jupiter in houses 4-6 or 10-12; feminine Moon, Mercury, Venus, Saturn in houses 1-3 or 7-9), Dina-Ratri (masculine planets in a day return, feminine in a night return). Houses are whole signs from the Varsha lagna, as Jagannatha Hora counts them.

Request parameters

locationoptional

string | null

City name to resolve to lat/lon/tz automatically. Example: 'Mumbai' or 'New Delhi, India'. If provided, latitude, longitude and timezone are not required.

nameoptional

string

Person name associated with the birth record

daterequired

string

Birth date in YYYY-MM-DD format

timerequired

string

Birth time in HH:MM 24-hour format. Required: this endpoint has no sunrise fallback.

latitudeoptional

number | null

Latitude. Required if location not provided.

longitudeoptional

number | null

Longitude. Required if location not provided.

timezoneoptional

string | null

IANA timezone. Required if location not provided (unless utc_offset is given). For dates before the zone adopted a standard time, the birthplace's local mean time (longitude / 15 hours) is used.

utc_offsetoptional

string | null

Optional explicit UTC offset of the birth time, as ±HH:MM or ±HH:MM:SS (e.g. '+04:51:31' for Bombay mean time). Overrides the offset timezone would give. Use it when the birth record states the offset, or for historical local times the IANA database cannot represent.

ayanamsaoptional

string

Sidereal ayanamsa mode used in calculations

target_yearrequired

integer

Varshaphal year, e.g. 2026: the solar return nearest the birthday in this year (in UT it can fall the day before or after the birthday, or on 31 December for a 1 January birthday). Each year gives a different return. Must not be before the birth year.

Response fields

success

boolean

True if the request succeeded

message

string

Human-readable status message

data

object

data.birth_time_provided

boolean

True when a birth time was supplied. False when it was not: house, Ascendant and Moon-dependent results then carry the accuracy limits of an unknown birth time.

data.target_year

integer

data.ayanamsa

string

data.solar_return_utc

string

data.is_day_return

boolean

data.varshaphal_ascendant_longitude

number

data.planets

array[object]

data.planets[].planet

string

data.planets[].harsha_bala

integer

Harsha Bala score for this planet (0-20).

data.planets[].max_harsha_bala

integer

data.planets[].varsha_house

integer

Planet's whole-sign house in the Varshaphal chart, counted from the Varsha Ascendant's sign.

data.planets[].rashi_index

integer

data.planets[].rashi

string

data.planets[].components

object

Breakdown of the 4 Harsha Bala components.

data.planets[].interpretation

string

Errors

api_key_invalid

Invalid API key format.

api_key_missing

API key is missing. Include it in the Authorization header as 'Bearer YOUR_KEY'.

api_key_not_found

The provided API key was not found. Verify the key in your Asterwise dashboard.

api_key_revoked

This API key has been revoked.

burst_limit_exceeded

Too many requests per minute. Please slow down.

internal_error

Something went wrong on our end. Please try again, or contact [email protected] if the problem persists. Include your request_id when contacting support.

ip_rate_limit_exceeded

Too many requests from this IP address. Please slow down.

monthly_usage_limit_exceeded

Monthly API call limit reached. Upgrade your plan to continue.

payload_too_large

Request body exceeds maximum allowed size of 64KB.

subscription_expired

Your subscription has expired. Please renew at asterwise.com/dashboard to continue.

validation_error

The request couldn't be processed. See the 'details' field for specific field-level issues.

Related endpoints

• Gochar — Transit Analysis
• Muhurta — Auspicious Timing
• Personal Nakshatra Prediction (Tarabala)
• Planetary transits — Gochar
• Prashna (Horary Chart)
• Tarabala and Chandrabala
• Varshaphal — Solar Return Chart
• Varshaphal — Tajika Saham Points
• Vedic daily factors
• Vedic events over a date range

Request

POST·application/json

curl

curl -X POST "https://api.asterwise.com/v1/astro/varshaphal/harsha-bala" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1985-11-12","time":"06:45","latitude":19.076,"longitude":72.8777,"timezone":"Asia/Kolkata","target_year":2026}'

Python

import asterwise
from asterwise.api.astrology_api import AstrologyApi
from asterwise.models.varshaphal_request import VarshaphalRequest

configuration = asterwise.Configuration(
    host="https://api.asterwise.com",
    access_token="YOUR_API_KEY",
)

request = VarshaphalRequest(
    date="1985-11-12",
    time="06:45",
    latitude=19.076,
    longitude=72.8777,
    timezone="Asia/Kolkata",
    target_year=2026,
)

with asterwise.ApiClient(configuration) as client:
    api = AstrologyApi(client)
    result = api.varshaphal_harsha_bala(varshaphal_request=request)
    print(result)

TypeScript

import { createClient, createConfig, varshaphalHarshaBala } from 'asterwise';

const client = createClient(createConfig({
  baseUrl: 'https://api.asterwise.com',
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
}));

const result = await varshaphalHarshaBala({
  client,
  body: {
      "date": "1985-11-12",
      "time": "06:45",
      "latitude": 19.076,
      "longitude": 72.8777,
      "timezone": "Asia/Kolkata",
      "target_year": 2026
  },
});

console.log(result.data);

Response

200 OK·application/jsonsigned

{
  "success": true,
  "message": "success",
  "data": {
    "target_year": 2026,
    "ayanamsa": "lahiri",
    "solar_return_utc": "2026-11-12T13:27:00Z",
    "is_day_return": false,
    "varshaphal_ascendant_longitude": 41.855459,
    "planets": [
      {
        "planet": "Sun",
        "harsha_bala": 5,
        "max_harsha_bala": 20,
        "varsha_house": 6,
        "rashi_index": 6,
        "rashi": "Tula",
        "components": {
          "sthana": {
            "earned": false,
            "points": 0,
            "happy_house": 9,
            "actual_house": 6,
            "description": "Sun is happy in the 9th house."
          },
          "swakshetra_uccha": {
            "earned": false,
            "points": 0,
            "in_own_sign": false,
            "in_exaltation": false,
            "current_rashi_index": 6
          },
          "pum_stri": {
            "earned": true,
            "points": 5,
            "gender": "male",
            "happy_hemisphere": "houses 4-6 and 10-12",
            "actual_house": 6
          },
          "dina_ratri": {
            "earned": false,
            "points": 0,
            "happy_period": "daytime return",
            "actual_period": "night"
          }
        },
        "interpretation": "Weak — planet is unhappy in this chart"
      },
      {
        "planet": "Moon",
        "harsha_bala": 10,
        "max_harsha_bala": 20,
        "varsha_house": 8,
        "rashi_index": 8,
        "rashi": "Dhanu",
        "components": {
          "sthana": {
            "earned": false,
            "points": 0,
            "happy_house": 3,
            "actual_house": 8,
            "description": "Moon is happy in the 3th house."
          },
          "swakshetra_uccha": {
            "earned": false,
            "points": 0,
            "in_own_sign": false,
            "in_exaltation": false,
            "current_rashi_index": 8
          },
          "pum_stri": {
            "earned": true,
            "points": 5,
            "gender": "female",
            "happy_hemisphere": "houses 1-3 and 7-9",
            "actual_house": 8
          },
          "dina_ratri": {
            "earned": true,
            "points": 5,
            "happy_period": "nighttime return",
            "actual_period": "night"
          }
        },
        "interpretation": "Moderate — some discomfort"
      },
      "... and 5 more items"
    ]
  }
}