POST/v1/astro/varshaphal
Varshaphal — Solar Return Chart
Computes the Varshaphal (annual horoscope) for a given year. Finds the exact moment when the Sun returns to its natal longitude (the return nearest the birthday in target_year; in UT it can fall a day either side, or on 31 December for a 1 January birthday), computes all planet positions at that moment, and returns Muntha (natal lagna sign + completed years, target_year minus birth year), the Varsha Pati (Tajika year lord, elected from the five Pancha Adhikaris) and Tajika Ithasala/Musaripha between the seven grahas. year_lord / vara_lord is the weekday lord at the return, not the Varsha Pati. Request JSON follows BirthInput plus target_year: name, date (YYYY-MM-DD), time (HH:MM, required), either location or latitude/longitude/timezone, ayanamsa.
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
Solar return instant (UTC, to the minute): the Sun back on its natal longitude, the return nearest the birthday in target_year.
data.solar_return_jd
number
data.natal_sun_longitude
number
data.natal_lagna
string
data.natal_lagna_index
integer
data.year_lord
string
Weekday (vara) lord at the solar-return instant, sunrise to sunrise at the birth place. Historical name: this is NOT the Tajika year lord. The year lord (Varsha Pati / Varsheshwara) is varsha_pati.planet. Same value as vara_lord.
data.vara_lord
string | null
Weekday (vara) lord at the solar-return instant (same value as year_lord).
data.muntha
object
data.muntha.rashi_index
integer
Muntha sign 0-11: natal lagna sign + age_years (one sign a year).
data.muntha.rashi
string
data.muntha.age_years
integer
Completed years for this varsha: target_year minus birth year (Tajika Neelakanthi), not read off the return's UTC date.
data.muntha.muntha_lord
string | null
data.planets
object
data.varshaphal_ascendant_longitude
number | null
Sidereal ascendant longitude at solar return (degrees).
data.varshaphal_ascendant_sign
string | null
Sanskrit sign name of the Varshaphal ascendant.
data.varshaphal_ascendant_sign_index
integer | null
Sign index 0-11 of the Varshaphal ascendant.
data.varsha_pati
object
data.varsha_pati.planet
string
data.varsha_pati.role
string
data.varsha_pati.pancha_vargeeya_bala
number
data.varsha_pati.kshetra_bala
number
data.varsha_pati.uchcha_bala
number
data.varsha_pati.election_fallback
string | null
When set, Varsha Pati was elected by fallback rather than highest aspecting score. Currently only 'muntha_pati_no_aspect'.
data.varsha_pati.moon_election
string | null
Moon election outcome: 'cancer_lagna_exception', 'nocturnal_tri_rasi_exception', 'disqualified', or null.
data.pancha_adhikaris
array[object]
data.pancha_vargeeya_bala
object
data.tajika_aspects
array[object]
data.tajika_planet_pairs
array[object]
Pairs of the seven grahas (no Rahu/Ketu) in Tajika aspect by sign: same sign (conjunction), 3rd/11th (mitra), 4th/10th (vikrama), 5th/9th (labha), 7th (shatru). Keys: planet_a, planet_b, house_a, house_b (whole-sign houses from the Varsha lagna), diff_ab, diff_ba, aspect_ab, aspect_ba, faster_planet (by mean motion: Moon, Mercury, Venus, Sun, Mars, Jupiter, Saturn), orb_degrees (gap between their degrees within sign), orb_limit (mean of the two Deeptamsas), is_ithsala (faster planet behind the slower one within orb_limit), ithsala_type ('poorna' within 1 degree, 'vartamana' otherwise, null when not ithsala), is_musaripha (faster planet already past, within orb_limit). Retrogression is not modelled.
Errors
Invalid API key format.
API key is missing. Include it in the Authorization header as 'Bearer YOUR_KEY'.
The provided API key was not found. Verify the key in your Asterwise dashboard.
This API key has been revoked.
Too many requests per minute. Please slow down.
Something went wrong on our end. Please try again, or contact [email protected] if the problem persists. Include your request_id when contacting support.
Too many requests from this IP address. Please slow down.
Monthly API call limit reached. Upgrade your plan to continue.
Request body exceeds maximum allowed size of 64KB.
Your subscription has expired. Please renew at asterwise.com/dashboard to continue.
The request couldn't be processed. See the 'details' field for specific field-level issues.