/v1/varshaphal/chart

Solar-return chart for a birth year with planet positions, muntha and varsha lord in one call.

What this tells you

Varshaphal is the Tajika annual chart, cast for the moment each year when the Sun returns to its natal longitude. The ascendant and planets at that moment describe the year until the next solar return. One call returns the solar-return moment, the 9 planets with whole-sign houses from the annual ascendant, the annual ascendant, the Muntha and the year lord (`varsha_lord`).

Birth details are unprefixed: `date`, `time`, `tz`, `lat`, `lon` (time defaults to 12:00 when omitted). `year` is the target year (1800–2200). `birth.*` parameters are not read by this endpoint. Signs and nakshatras are indexes; map them to names in your app.

Request

All requests require an Authorization header with your dv_live_* API key.

example request

curl "https://api.lifeastroapi.com/v1/varshaphal/chart?date=1990-01-15&tz=Asia%2FKolkata&lat=19.076&lon=72.8777&year=2026&time=10%3A30" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query parameters

Checked against the API: a parameter is marked required when the request fails without it.

Name	Required	Example	Description
`date`	yes	`1990-01-15`	Birth date (YYYY-MM-DD).
`tz`	yes	`Asia/Kolkata`	Birth place timezone: IANA name (Asia/Kolkata) or UTC offset (+05:30).
`lat`	yes	`19.076`	Birth place latitude in decimal degrees.
`lon`	yes	`72.8777`	Birth place longitude in decimal degrees.
`year`	yes	`2026`	Gregorian year of the solar return to compute.
`time`	no	`10:30`	Birth time (HH:MM, 24-hour, local). Defaults to 12:00.
`ayanamsa`	no	—	Ayanamsa (sidereal offset) to use. Defaults to lahiri.

Response (200 OK)

The real response to the example request above, generated from the API itself. Long arrays are trimmed to their first two items. Field names are stable across versions.

200 response

{
  "natal_date": "1990-01-15",
  "target_year": 2026,
  "lat": 19.076,
  "lon": 72.8777,
  "ayanamsa": "lahiri",
  "chart": {
    "target_year": 2026,
    "solar_return_jd": 2461055.942921,
    "solar_return_iso": "2026-01-15T10:37:48Z",
    "planets": [
      {
        "name": "Sun",
        "sidereal_lon": 271.063315,
        "sign_index": 9,
        "deg_in_sign": 1.063315,
        "dms_in_sign": "01°03'47\"",
        "house": 8,
        "nakshatra_idx": 20,
        "pada": 2,
        "nak_lord": "Sun",
        "speed": 1.018813,
        "is_retro": false,
        "ecl_lat": -0.000146
      },
      {
        "name": "Moon",
        "sidereal_lon": 233.166758,
        "sign_index": 7,
        "deg_in_sign": 23.166758,
        "dms_in_sign": "23°10'00\"",
        "house": 6,
        "nakshatra_idx": 17,
        "pada": 2,
        "nak_lord": "Mercury",
        "speed": 11.966956,
        "is_retro": false,
        "ecl_lat": -5.082821
      }
    ],
    "ascendant": {
      "sidereal_lon": 61.948902,
      "sign_index": 2,
      "deg_in_sign": 1.948902,
      "dms_in_sign": "01°56'56\"",
      "nakshatra_idx": 4,
      "pada": 3,
      "nak_lord": "Mars",
      "mc": 321.900394,
      "house_system": "whole_sign"
    },
    "muntha": {
      "rashi_index": 10,
      "house": 1
    },
    "varsha_lord": {
      "planet": "Sun",
      "hora_number": 10
    }
  }
}

Field reference

Every field in the response, with its type, a real example, and what it means.

Field	Type	Meaning
natal_date	string (YYYY-MM-DD)	Birth date (`date` parameter), echoed. example: `"1990-01-15"`
target_year	integer	Year of the solar return (`year` parameter). example: `2026`
lat	number	Birth latitude. The annual chart is cast for the birth place. example: `19.076`
lon	number	Birth longitude. example: `72.8777`
ayanamsa	string	Ayanamsa used (default lahiri). example: `"lahiri"`
chart.solar_return_jd	number	Julian Day (UT) of the solar return: the moment in target_year when the Sun returns to the sidereal longitude it had at birth (ayanamsa taken at each moment). example: `2461055.942921`
chart.solar_return_iso	string (RFC 3339, UTC)	Same moment in UTC ("Z"). Convert to the user's timezone for display. example: `"2026-01-15T10:37:48Z"`
chart.planets[]	array (9 items)	Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu at the solar return (Rahu/Ketu mean node). example: `[…]`
chart.planets[].name	string	Planet name. Localised with `locale`. These planets have no `id` field. example: `"Sun"`
chart.planets[].sidereal_lon	number (0–360)	Sidereal longitude in degrees. example: `271.063315`
chart.planets[].sign_index	integer (0–11)	Sign index (0 = Aries). example: `9`
chart.planets[].deg_in_sign	number (0–30)	Degrees within the sign. example: `1.063315`
chart.planets[].dms_in_sign	string	Degrees within the sign as DD°MM'SS". example: `"01°03'47\""`
chart.planets[].house	integer (1–12)	Whole-sign house counted from the annual ascendant. example: `8`
chart.planets[].nakshatra_idx	integer (0–26)	Nakshatra index (0 = Ashwini). example: `20`
chart.planets[].pada	integer (1–4)	Nakshatra pada. example: `2`
chart.planets[].nak_lord	string	Vimshottari lord of the nakshatra. Localised with `locale`. example: `"Sun"`
chart.planets[].speed	number	Longitude speed in degrees per day. example: `1.018813`
chart.planets[].is_retro	boolean	True when speed is negative. example: `false`
chart.planets[].ecl_lat	number	Geocentric ecliptic latitude in degrees (north positive). Decides a graha yuddha: the planet further north wins. Left out for Rahu and Ketu, which sit on the ecliptic. example: `-0.000146`
chart.ascendant	object	Annual (varsha) lagna at the solar return. example: `{ "sign_index": 7, "deg_in_sign": 18.654763, … }`
chart.ascendant.sidereal_lon	number (0–360)	Sidereal longitude of the annual ascendant. example: `61.948902`
chart.ascendant.sign_index	integer (0–11)	Sign of the annual ascendant (0 = Aries). example: `2`
chart.ascendant.nakshatra_idx	integer (0–26)	Nakshatra of the annual ascendant. example: `4`
chart.ascendant.mc	number (0–360)	Sidereal longitude of the midheaven (MC). example: `321.900394`
chart.ascendant.house_system	string	Always "whole_sign" here. example: `"whole_sign"`
chart.muntha.rashi_index	integer (0–11)	Muntha sign (0 = Aries … 11 = Pisces): the natal ascendant sign moved forward one sign for each completed year of age (one sign per solar return). example: `10`
chart.muntha.house	integer (1–12)	House of the Muntha counted from the natal ascendant sign (1 = natal lagna sign). It is not counted from the annual ascendant. example: `1`
chart.varsha_lord.planet	string	Lord of the planetary hora running at the solar-return moment at the birth place. One of the 7 classical planets. Localised with `locale`. example: `"Sun"`
chart.varsha_lord.hora_number	integer (1–24)	Hora number of that moment, counted from local sunrise: 1–12 are day horas, 13–24 night horas. example: `10`

Usage tips

How to use it

Everything in one call
`chart` already contains `muntha` and `varsha_lord`. Call /v1/varshaphal/muntha or /v1/varshaphal/lord (10 credits each) only when you need just that value.
Muntha from the annual ascendant
For the usual Tajika reading of the Muntha house, use ((chart.muntha.rashi_index − chart.ascendant.sign_index + 12) mod 12) + 1. `chart.muntha.house` is counted from the natal ascendant instead.
Use with yearly-bhavishyafal
For narrative content, call /v1/vedic/narrative/yearly-bhavishyafal (30 credits), which combines varshaphal themes, dasha, Sade Sati and transits in one response.

Errors

Every error follows the same envelope. Use the error.code field (not the message) for conditional logic in your integration.

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

402 Payment Required

{
  "error": {
    "code": "trial_exhausted",
    "message": "your free trial credits are exhausted — pick a plan to continue",
    "top_up_url": "https://lifeastroapi.com/pricing",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded; retry after 12 seconds",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

Try it

Get a dv_live_* key from your dashboard and paste into the cURL snippet above. New accounts get 1,500 free credits. Sign up.