/v1/vedic/narrative/yearly-bhavishyafal

Personalized yearly horoscope from 6000+ rules: Varshaphal themes + active Dasha + Sade Sati phase + slow-mover transits + marriage/career/finance outlook — all anchored to the solar return.

What this tells you

Yearly Bhavishyafal is a fully personalized yearly horoscope — 30 credits. **Why 30 credits?** This is the most compute-intensive narrative endpoint. Under the hood, one call runs: 1. Solar return computation — binary-search for the exact moment Sun returns to its natal longitude (heavy ephemeris scan) 2. Active Vimshottari dasha at that solar return moment 3. Saturn's current phase — sade sati check against birth Moon sign 4. All slow-mover transit positions (Jupiter, Saturn, Rahu, Ketu, Mars) 5. Up to 14 corpus lookups from our authored Vedic rule corpus Running these separately would cost: varshaphal/chart (30) + dasha/vimshottari/current (10) + transit/positions (10) + transit/sade-sati (10) = **60 credits**. We combine all of it for 30 credits. **Personal, not generic:** a sun-sign yearly horoscope gives the same paragraph to everyone born under that sign. Yearly Bhavishyafal is unique for every person: it uses their actual birth chart, computes the solar return for the specific year, checks their active dasha, and looks up authored rules that match their exact Muntha house + Varsha lord + dasha stack + sade-sati status. No two people get the same response.

Request

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

example request

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

Query parameters

Name	Type	Required	Description
`birth.date`	string	yes	Date of birth (YYYY-MM-DD)
`birth.time`	string	yes	Time of birth (HH:MM)
`birth.tz`	string	yes	Birth timezone
`lat`	number	yes	Birth latitude (for solar return)
`lon`	number	yes	Birth longitude (for solar return)
`year`	integer	yes	Target year for the horoscope (e.g. 2027)

Response (200 OK)

Successful requests return a JSON body. Field names are stable across versions.

200 response

{
  "sections": [
    {
      "rule_id": "vedic.L2.varshaphal.muntha_in_9",
      "axis": "varshaphal",
      "heading": "Muntha in the 9th House — Dharma, Fortune, and Long Journeys",
      "body": "The Muntha (progressed ascendant) falling in the 9th house this year…",
      "citations": ["Tajika Neelakanthi 3.8"]
    },
    {
      "rule_id": "vedic.L2.varshaphal.varsha_lord_jupiter",
      "axis": "varshaphal",
      "heading": "Jupiter as Varsha Lord — Expansion, Wisdom, and Growth",
      "body": "With Jupiter holding the year-lordship…",
      "citations": ["Tajika Shastra 2.5"]
    },
    {
      "rule_id": "vedic.L2.dasha.venus_mercury_sun",
      "axis": "dasha",
      "heading": "Venus–Mercury–Sun Dasha Period",
      "body": "The current Vimshottari dasha stack of Venus (MD) — Mercury (AD) — Sun (PD)…"
    },
    {
      "rule_id": "vedic.L1.sade_sati.rising",
      "axis": "sade_sati",
      "heading": "Sade Sati — Rising Phase",
      "body": "Saturn is beginning its 2.5-year transit over the sign preceding your Moon…"
    },
    {
      "rule_id": "vedic.L2.transit.jupiter_in_gemini",
      "axis": "transit",
      "heading": "Jupiter Transiting Gemini",
      "body": "Jupiter's transit through Gemini activates communication, short travel…"
    },
    "… (up to 14 sections: 2 varshaphal + 3 dasha + 1 sade-sati + 5 transits + 3 outlooks)"
  ],
  "skipped": {},
  "tier": "silver"
}

Field reference

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

Field	Type	Meaning
sections[].rule_id	string	The exact corpus rule that generated this section. Follows the L1/L2/L3 layer taxonomy. example: `"vedic.L2.varshaphal.muntha_in_9"` Jyotish: L2 rules are time-bound (vary by year). L1 are birth-chart static. L3 are composite multi-feature narratives.
sections[].axis	string	Which astrological system generated this section. example: `"varshaphal" \| "dasha" \| "sade_sati" \| "transit" \| "outlook"`
sections[].body	string	The authored narrative text. Typically 100–300 words per section, written by Jyotish experts. example: `"Jupiter as year lord brings expansion…"`
sections[].citations	string[]	Classical text references for the interpretation. example: `["Tajika Neelakanthi 3.8"]`
tier	string	Which content tier was used. Silver returns L1+L2 rules; Gold unlocks L3 composite outlooks. example: `"silver"`
year (input param)	integer	Target year for the horoscope. All calculations anchor to the solar return moment for that year. example: `2027`

Usage tips

How to use it

Why 30 credits — what you get
Up to 14 authored sections covering: 2 Varshaphal themes (Muntha house + Varsha lord) + up to 3 Dasha sections (MD/AD/PD stack) + 1 Sade Sati section + up to 5 transit narratives (Jupiter/Saturn/Rahu/Ketu/Mars) + 3 life-area outlooks (marriage/career/finance). Each section is 100–300 words with classical citations.
Not a generic horoscope — fully personal
Unlike sun-sign horoscopes, this uses the person's birth chart. Two people born on the same day but different times get completely different Bhavishyafals because their dasha stack and Muntha house differ.
Generate once per year per user
Cache per (birth-data + year). The response only changes when the year changes. At 30 credits (about ₹0.24 on the Pro plan) it is the richest single call in the API — 14 sections of personalized content for less than half a rupee.
Surface the dasha section prominently
The dasha section (axis: "dasha") is the most personal. If you show only 3 sections, pick: varshaphal + dasha + the most relevant transit.
Upsell from kundli flow
After showing a user their birth chart, offer "Your 2027 Bhavishyafal" — call this with ?year=2027. The personalized result is a natural premium feature.

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.