/v1/varshaphal/lord

Varsha lord (year lord).

What this tells you

The year lord for a Varshaphal year. This endpoint returns the lord of the hora (planetary hour) in which the solar return falls, computed at the birth place. Hora lords follow the Chaldean order, starting from the weekday lord at local sunrise. Classical Tajika texts also describe choosing the year lord from five office-bearers (Panchadhikari); this endpoint does not do that selection.

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.

Request

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

example request

curl "https://api.lifeastroapi.com/v1/varshaphal/lord?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`	Year (YYYY).
`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,
  "ayanamsa": "lahiri",
  "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`
ayanamsa	string	Ayanamsa used (default lahiri). example: `"lahiri"`
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"`
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

Pair with Muntha
Varsha lord plus Muntha sign make a two-line summary of a yearly reading. /v1/varshaphal/chart returns both in one call.

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.