Vedic Astrology API: Avasthas, Arudha and Chara Karakas

Most Vedic APIs stop at the D1 chart. You get sidereal longitudes, rashis, bhavas, a nakshatra with a pada, and then the response ends. That is enough to draw a kundli and nothing more, because the readings a practitioner actually gives are built on a second layer: which yogas formed, what condition each graha is in, where the perceived image of a bhava sits, and which graha carries the soul office in this particular birth. That layer is where Jyotish stops being a coordinate dump and starts being a reading. This post walks the four calculations that make it up, with real captured production responses from the RoxyAPI Vedic Astrology API, and it is explicit about what is detected from a chart and what is only a lookup.

What does a Vedic astrology API return beyond planets and houses?

Beyond positions, a practitioner-grade Vedic response needs four things: yoga verdicts computed from the chart, avastha states qualifying each graha, the Arudha padas that describe how each bhava is perceived, and the Jaimini Chara Karakas. All four are pure chart arithmetic over the D1 placements, so a disagreement with another program is always a school choice rather than a position error.

Ready to build this? The Vedic Astrology API ships all four behind one key, alongside 50+ Vedic endpoints that are part of 171+ endpoints across 12+ insight domains. See pricing.

How do 44 yoga verdicts carry a family tag and a suppression reason?

Every verdict names the group it belongs to. Twelve are classical single combinations such as Gajakesari and the Pancha Mahapurusha set. The other thirty two are Nabhasa yogas, the whole-chart shape yogas Parashara sets out in the Brihat Parashara Hora Shastra and Varahamihira treats in Brihat Jataka. They split into four families, and the family is what decides precedence when two of them fire on the same chart.

A Sankhya yoga is selected purely by rashi count, so exactly one matches every chart ever cast. Classically it is silenced whenever any other Nabhasa yoga is present, which is the rule most implementations quietly skip. RoxyAPI returns the silenced verdict anyway, with present: false and a suppressedBy field naming the family that outranked it. Here are two real entries from one chart, trimmed to the decision fields:

{
  "id": "sarpa",
  "name": "Sarpa Yoga",
  "quality": "Negative",
  "family": "dala",
  "present": true,
  "evidence": "Sun, Mars and Saturn all occupy kendras from the Lagna, with no benefic in a kendra"
}

{
  "id": "damni",
  "name": "Damni Yoga",
  "quality": "Positive",
  "family": "sankhya",
  "present": false,
  "suppressedBy": "dala",
  "evidence": "The seven visible grahas occupy 6 rasis, but another Nabhasa yoga is present and classically suppresses Sankhya"
}

For the detection rules themselves, the companion post on Vedic yoga detection goes combination by combination.

What do the three avastha systems tell you about a graha?

A chart says where a graha is. An avastha says how much of its promise it can keep. Parashara devotes chapter 45 of the Brihat Parashara Hora Shastra to these states and says plainly in shloka 10 that the bhava a graha occupies takes on the character of that state. RoxyAPI computes three of these systems at once on every D1 birth chart.

Send avasthaInfo: true on the birth-chart request and each graha also carries a short meaning and a one sentence classical reading. This is a real meta.Jupiter entry from a production response:

{
  "graha": "Jupiter",
  "rashi": "Pisces",
  "house": 12,
  "awastha": "Mrita",
  "jagradadi": "Jagrat",
  "deeptadi": "Svastha",
  "avasthaInfo": {
    "awastha": {
      "meaning": "Spent",
      "interpretation": "At the far edge of the sign the graha is spent, and the results it signifies do not materialise."
    },
    "jagradadi": {
      "meaning": "Awake",
      "interpretation": "In its own sign or exaltation the graha is fully alert and gives its results without hindrance."
    },
    "deeptadi": {
      "meaning": "At home",
      "interpretation": "In its own sign the graha is healthy and settled, granting property, standing among its own people, and steady means."
    }
  }
}

That single graha is the whole argument for reading all three: Jupiter is in its own sign and fully awake, and simultaneously at the burnt-out edge of that sign. Rahu, Ketu and the Lagna return null for jagradadi and deeptadi on purpose, because they own no sign and any dignity state for them would be invented. All 17 states are also served standalone by GET /vedic-astrology/avasthas, filterable with ?system=jagradadi.

How to calculate the twelve Arudha padas from a birth chart

Resolve the birth place first. Never make a user type coordinates, and never guess a UTC offset for a historical date.

curl -s "https://roxyapi.com/api/v2/location/search?q=London&limit=1" \
  -H "X-API-Key: YOUR_KEY"

{
  "total": 4,
  "limit": 1,
  "offset": 0,
  "cities": [
    {
      "city": "London",
      "province": "England",
      "country": "United Kingdom",
      "iso2": "GB",
      "latitude": 51.50853,
      "longitude": -0.12574,
      "timezone": "Europe/London",
      "utcOffset": 1,
      "population": 7556900
    }
  ]
}

Feed latitude, longitude and the IANA timezone string straight into POST /vedic-astrology/arudha. The IANA name is resolved to the offset that was actually in force on that date.

curl -s -X POST "https://roxyapi.com/api/v2/vedic-astrology/arudha" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1999-02-11",
    "time": "10:12:00",
    "latitude": 51.50853,
    "longitude": -0.12574,
    "timezone": "Europe/London"
  }'

const res = await fetch('https://roxyapi.com/api/v2/vedic-astrology/arudha', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ROXYAPI_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    date: '1999-02-11',
    time: '10:12:00',
    latitude: 51.50853,
    longitude: -0.12574,
    timezone: 'Europe/London',
  }),
});
const { arudhaLagna, upapada, padas } = await res.json();

import os, requests

r = requests.post(
    "https://roxyapi.com/api/v2/vedic-astrology/arudha",
    headers={
        "X-API-Key": os.environ["ROXYAPI_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "date": "1999-02-11",
        "time": "10:12:00",
        "latitude": 51.50853,
        "longitude": -0.12574,
        "timezone": "Europe/London",
    },
)
data = r.json()
print(data["arudhaLagna"], data["upapada"])

The pada of a bhava is found by counting from the bhava to its lord, then counting the same distance again. When that lands back in the bhava itself or in the seventh from it, the classical exception moves it to the tenth from there, because a reflection cannot sit on top of its source. That step is the one implementations most often drop, so it is reported as a boolean:

{
  "lagnaRashi": "Aries",
  "arudhaLagna": "Capricorn",
  "upapada": "Sagittarius",
  "padas": [
    {
      "id": "a1",
      "abbreviation": "AL",
      "name": "Arudha Lagna",
      "house": 1,
      "bhavaRashi": "Aries",
      "lord": "Mars",
      "lordRashi": "Libra",
      "rashi": "Capricorn",
      "houseFromLagna": 10,
      "exceptionApplied": true,
      "meaning": "Public image"
    }
  ]
}

Check it by hand. Aries to Libra is seven signs inclusive, and seven onward from Libra returns to Aries, which is the bhava itself, so the pada moves to the tenth from Aries and lands in Capricorn.

Why does the Chara Karaka scheme change the Atmakaraka?

Jaimini Upadesa Sutras 1.1.10 ranks the grahas by how far each has advanced into its sign, highest first, and the sutra itself says the ranking runs over the seven or the eight. Both readings are classical, so POST /vedic-astrology/chara-karakas exposes the choice as a scheme parameter rather than deciding for you. The eight scheme adds Rahu and the Pitrikaraka office; the seven ranks only the classical grahas and drops it. Ketu is excluded from both, since it mirrors the Rahu degree exactly.

scheme goes in the request body, not the query string. That distinction matters more than it looks: a query-string scheme is ignored rather than rejected, so the call returns 200 with the default eight-scheme ranking and nothing tells you the choice was dropped.

curl -s -X POST "https://roxyapi.com/api/v2/vedic-astrology/chara-karakas" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-12-01","time":"12:00:00","latitude":0,"longitude":0,
       "timezone":"UTC","scheme":"seven"}'

Rahu is the reason the two schemes diverge. It advances backward through a sign, so its ranking degree is measured from the end. The response returns both numbers so the ordering can be audited without knowing the rule:

{
  "id": "gnatikaraka",
  "abbreviation": "GK",
  "graha": "Rahu",
  "rashi": "Cancer",
  "degreeInRashi": 28.363381576847075,
  "rankingDegree": 1.6366184231529246,
  "isReversed": true,
  "meaning": "Relatives and obstacles"
}

On the 1999 chart used earlier the two schemes agree on the Atmakaraka but shuffle the offices below it. Saturn holds Pitrikaraka under eight and Putrakaraka under seven; Mercury moves from Putrakaraka to Gnatikaraka. On other charts the divergence reaches the top: for 2026-12-01 at 12:00 UTC the eight scheme returns Rahu as Atmakaraka and the seven scheme returns Mercury. Hardcoding either would silently contradict whichever reference your users already trust.

Which fields let an app explain a verdict instead of asserting it?

Every one of these calculations is a judgement a user can and will dispute, so each response carries the derivation next to the answer. That is the difference between an app that says Sarpa Yoga is present and an app that can show why, and it is what lets a support reply end in a citation rather than a shrug.

The underlying positions carry a median deviation of 1.5 arcseconds, about 0.0004 degrees, from NASA JPL Horizons, so a boundary case is a school choice to argue about rather than an arithmetic difference. Interpretations and state readings are localized through ?lang=, covering eight languages including Hindi, so a Jagradadi reading arrives in the language the user reads.

FAQ

What is the Arudha Lagna and how is it calculated?

The Arudha Lagna is the perceived image of the first house, as opposed to the self the Lagna describes. It is found by counting from the Lagna to its lord and then the same distance onward from the lord, with a classical exception that moves the result to the tenth house when it lands in the Lagna itself or in the seventh. RoxyAPI returns it as arudhaLagna on POST /vedic-astrology/arudha, alongside all twelve padas and an exceptionApplied flag on each.

Does RoxyAPI detect Raja Yoga and Dhana Yoga automatically?

No. Raja Yoga and Dhana Yoga exist in the RoxyAPI reference glossary of more than 300 classical yoga entries, reachable through GET /vedic-astrology/yoga/{id}, but they are lookups rather than chart detections. The automatically detected set is 44 verdicts per chart: twelve classical combinations plus all thirty two Nabhasa yogas, each returned with the evidence for the decision.

What is the difference between the seven and eight Chara Karaka schemes?

The eight scheme ranks Rahu alongside the seven classical grahas and includes the Pitrikaraka office; the seven scheme ranks only the classical grahas and drops Pitrikaraka. Jaimini Upadesa Sutras 1.1.10 sanctions both. Because Rahu is ranked by its degree measured backward from the end of its sign, the two schemes can name a different Atmakaraka for the same birth, so RoxyAPI exposes scheme as a request parameter instead of choosing for you.

What is an avastha in Vedic astrology?

An avastha is the state or condition of a graha, which qualifies how much of its promised result actually arrives. RoxyAPI computes three systems on every birth chart: Baladi, the five age states set by degree within the sign; Jagradadi, the three waking states set by sign dignity; and Deeptadi, the nine dispositional states. All 17 readings are also available on their own through GET /vedic-astrology/avasthas.

Is there an API that returns the Atmakaraka for a birth chart?

Yes. POST /vedic-astrology/chara-karakas takes a date, time, latitude, longitude and timezone and returns the Atmakaraka at the top level, plus the full ranked list of karaka offices with the degree each was ranked on. The Darakaraka is lifted to the top level too, since it is the second most requested value.

Can I get Vedic readings in a language other than English?

Yes. Add ?lang= to any translated endpoint and the interpretations, avastha readings and yoga glossary text come back localized. Eight languages are covered, including Hindi, and the machine-readable keys such as family, id and system stay in English so grouping and filtering logic works identically in every locale.

Conclusion

Yoga verdicts with evidence, three avastha systems on every graha, twelve Arudha padas with the derivation attached, and Chara Karakas under either classical scheme are the layer that turns a chart into a reading. Every one of them is a single POST with a birth date, a time and a place. Start with the Vedic Astrology API and run any of these endpoints live in the browser first, no signup and no key required.