---
title: "Varshaphal — Harsha Bala"
method: POST
path: "/v1/astro/varshaphal/harsha-bala"
tags: ["Astrology"]
---

# Varshaphal — Harsha Bala

`POST /v1/astro/varshaphal/harsha-bala`

## Request

- Base URL: `https://api.asterwise.com`
- URL: `https://api.asterwise.com/v1/astro/varshaphal/harsha-bala`
- Auth: HTTP bearer

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 body

- VarshaphalRequest: Varshaphal — extends :class:`TimedBirthInput` with ``target_year``. Birth fields: ``name``, ``date``, ``time``, ``location`` or coordinates, ``ayanamsa``. Required: ``target_year`` (solar return year).
  - `location` string, nullable: City name to resolve to lat/lon/tz automatically. Example: 'Mumbai' or 'New Delhi, India'. If provided, latitude, longitude and timezone are not required.
  - `name` string: Person name associated with the birth record
  - `date` string, required: Birth date in YYYY-MM-DD format
  - `time` string, required: Birth time in HH:MM 24-hour format. Required: this endpoint has no sunrise fallback.
  - `latitude` number, nullable: Latitude. Required if location not provided.
  - `longitude` number, nullable: Longitude. Required if location not provided.
  - `timezone` string, nullable: 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_offset` string, nullable: 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.
  - `ayanamsa` 'lahiri' | 'raman' | 'kp' | 'tropical': Sidereal ayanamsa mode used in calculations
  - `target_year` integer, required: 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 `200`

Successful Response

- ApiResponseHarshaBalaResponse
  - `success` boolean: True if the request succeeded
  - `message` string: Human-readable status message
  - `data` HarshaBalaResponse, required
    - `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.
    - `target_year` integer, required
    - `ayanamsa` string, required
    - `solar_return_utc` string, required
    - `is_day_return` boolean, required
    - `varshaphal_ascendant_longitude` number, required
    - `planets` HarshaBalaEntry[], required
      - `planet` string, required
      - `harsha_bala` integer, required: Harsha Bala score for this planet (0-20).
      - `max_harsha_bala` integer
      - `varsha_house` integer, required: Planet's whole-sign house in the Varshaphal chart, counted from the Varsha Ascendant's sign.
      - `rashi_index` integer, required
      - `rashi` string, required
      - `components` object, required: Breakdown of the 4 Harsha Bala components.
      - `interpretation` string, required

## Other responses

- `401`: Authentication failed
- `403`: Authorization failed
- `404`: Resource not found
- `413`: Payload too large
- `422`: Validation error
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream provider error
- `503`: Service unavailable

---

[API](https://skmtc.dev/asterwise/apis/asterwise-api.md) · [All operations](https://skmtc.dev/asterwise/apis/asterwise-api/llms.txt) · [OpenAPI document](https://skmtc.dev/asterwise/apis/asterwise-api/revisions/3c4bbb1194e2?raw)