Varshaphal

asterwise_get_varshaphal

Computes the annual Tajika-style solar return for a four-digit civil year and returns Muntha, Pancha Adhikari metrics, Tajika aspects, and varshaphal positions.

Parameters

Parameter	Type	Required	Description
birth	object	yes	Birth data for tools that need the exact birth time (no sunrise fallback). Required fields: date, time, lat, lon. Optional fields: person_name, timezone, ayanamsa.
year	integer	yes	Varshaphal year, four digits, e.g. 2026: the solar return nearest the birthday in that year (in UTC it can fall a day either side, or on 31 Dec for a 1 Jan birthday). Must not be before the birth year.
response_format	enum: markdown, json	no	Output format: 'markdown' (default) for a readable report, or 'json' for the raw structured payload.

What it covers

Varshaphal engine: solar return instant, weekday (vara) lord, muntha block, varsha pati election, five pancha adhikaris with bala components, tajika aspect arrays, and pairwise Tajika geometry including ithsala/musaripha flags. year must mean calendar year (e.g. 2026), not biological age — not enforced locally; wrong integers chart the wrong annual return. Not lifetime Vimshottari (asterwise_get_dasha) nor generic transit ingress lists (asterwise_get_transits). data.year_lord is the weekday (vara) lord, kept under its old name; the Tajika year lord (Varsheshwara) is data.varsha_pati.planet.

Workflow

BEFORE: RECOMMENDED — asterwise_get_natal_chart — baseline radix before annual overlay.
AFTER: None.

Input

year is a plain int sent as target_year upstream; callers must supply the true Gregorian return year, not age.

Output contract

data.target_year (int)
data.ayanamsa (string)
data.solar_return_utc (string — ISO)
data.solar_return_jd (float)
data.natal_sun_longitude (float)
data.natal_lagna (string)
data.natal_lagna_index (int)
data.year_lord (string — weekday (vara) lord at the return; NOT the Tajika year lord, which is varsha_pati.planet)
data.vara_lord (string — same value as year_lord)
data.muntha:
rashi_index (int)
rashi (string)
age_years (int — completed years = target_year − birth year; Muntha = natal lagna sign + age_years)
muntha_lord (string or null)
data.planets{} — keys Sun..Ketu:
longitude (float)
rashi_index (int)
rashi (string)
degree (float)
is_retrograde (bool)
speed (float)
data.varshaphal_ascendant_longitude (float)
data.varshaphal_ascendant_sign (string — Sanskrit sign name derived from the ascendant longitude)
data.varshaphal_ascendant_sign_index (int — sign index 0-11, where 0=Mesha and 11=Meena)
data.varsha_pati:
planet (string)
role (string)
pancha_vargeeya_bala (float)
kshetra_bala (float)
uchcha_bala (float)
election_fallback (string or null — 'muntha_pati_no_aspect' when no adhikari aspects the Varsha Lagna, so the Muntha Pati is taken; else null)
moon_election (string or null — 'cancer_lagna_exception' or 'nocturnal_tri_rasi_exception' when the Moon is elected under that exception, 'disqualified' when the Moon aspected but was passed over; else null)
data.pancha_adhikaris[] — five objects:
role (string)
planet (string)
pancha_vargeeya_bala, kshetra_bala, uchcha_bala, hadda_bala, dreshkana_bala, navamsa_bala (floats)
aspects_ascendant (bool)
tajika_aspect_houses_matched[] (int array)
tajika_aspect_angles_matched[] (array)
separation_from_asc_deg (float)
data.pancha_vargeeya_bala{} — keyed by role (float values)
data.tajika_aspects[] — one per Pancha Adhikari:
planet (string)
role (string)
separation_from_asc_deg (float)
matched_standard_angles[] (array)
aspect_house_from_lagna (int)
aspects_ascendant (bool)
data.tajika_planet_pairs[] — each:
planet_a, planet_b (strings)
house_a, house_b (int)
diff_ab, diff_ba (int — house distance each way)
aspect_ab, aspect_ba (string — Tajika aspect name, e.g. 'mitra', 'labha', 'shatru', 'vikrama', plus 'conjunction' for the same sign; seven grahas only (no Rahu/Ketu); houses are whole sign)
is_ithsala (bool)
ithsala_type ('poorna' | 'vartamana' | null)
is_musaripha (bool)
faster_planet (string — by mean motion: Moon > Mercury > Venus > Sun > Mars > Jupiter > Saturn)
orb_degrees (float — gap between the two planets' degrees within their signs)
orb_limit (float — mean deeptamsa)

Response format

response_format=json serialises the complete response as indented JSON — use this for programmatic parsing, typed clients, and downstream tool chaining. response_format=markdown renders the same data as a human-readable report. Both modes return identical underlying data — no fields are added, removed, or filtered by either mode.

Compute class

MEDIUM_COMPUTE

Errors

INVALID_PARAMS (local — caught before upstream call):
None — year not range-checked here.

INVALID_PARAMS (upstream):
— Upstream 422 if year is before the birth year; surfaces as MCP INTERNAL_ERROR with the API message.

INTERNAL_ERROR:
— Any upstream API failure or timeout → MCP INTERNAL_ERROR

Edge cases:
— Feeding age instead of civil year silently mis-orients the return — caller responsibility.

Do not confuse with

asterwise_get_dasha — multi-decade Vimshottari, not one solar return.
asterwise_get_transits — ingress/station timeline, not annual Tajika chart.

Connect

Remote MCP endpoint: https://mcp.asterwise.com/mcp. Authenticate with Authorization: Bearer <API key> or OAuth. See the MCP setup guide.