Theo: planet strength & disposition¶

Two questions the Theo system answers separately, and one it answers alongside them:

Question	Field	Range	Endpoint
How much can this planet do?	`strength`	Shadbala over the classical requirement; `1.0` is "able"	`/theo/planets`
*How kindly does it act here?*	`disposition`	−1.0 … +1.0, with a plain-words band	`/theo/planets`
How tied is it to the rest of the chart?	`connection`	≥ 0, unsigned	`/theo/planets`, `/influence-network`

These three are never collapsed into one number

A strong malefic and a weak benefic are different situations, and a planet that is heavily connected to a chart may be helping or hurting. Any product that multiplies strength by kindness, or reads a connection as a verdict, is inventing a quantity the tradition does not have. Each field is published on its own so your UI can decide what to show — the API will not decide it for you.

Every response carries method_version. Pin it if your product's copy depends on the exact numbers; it changes when the model changes, and the changelog says how.

`GET /v1/vedic/charts/{id}/theo/planets`¶

Where each of the nine grahas stands in this chart. Scope charts:read. Requires a Vedic chart — a Western one returns 422 with "reason": "unsupported_astrology_system", as does /theo/houses.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.astrolinkers.com/v1/vedic/charts/$CHART/theo/planets"

{
  "chart_id": "019febf3-2900-7542-9982-f00048b6da70",
  "method_version": "theo-strength-disposition-v2",
  "planets": [
    {
      "planet": "sun",
      "strength": {
        "virupa": 584.19,
        "rupas": 9.74,
        "required_rupas": 5.0,
        "ratio": 1.947,
        "rank": 1,
        "components": {
          "naisargika": 60.0,
          "dig": 30.0,
          "uchcha": 43.23,
          "drik": -96.77,
          "kala": 197.19,
          "chesta": 110.54,
          "sthana": 240.0
        },
        "missing": [],
        "complete": true
      },
      "disposition": {
        "score": 0.08,
        "band": "mixed",
        "terms": [
          {"name": "functional_nature", "score": -0.6, "weight": 0.3,
           "reason": "malefic for a gemini lagna"},
          {"name": "dignity", "score": 0.2, "weight": 0.25, "reason": "friend"},
          {"name": "house", "score": 0.6, "weight": 0.2,
           "reason": "house 1 from the lagna"},
          {"name": "association", "score": 0.598, "weight": 0.15,
           "reason": "80% of the influence on it is from friends"},
          {"name": "condition", "score": 0.0, "weight": 0.1,
           "reason": "no affliction of state"}
        ]
      },
      "connection": {"received": 302.11, "given": 182.0}
    },
    "…8 more bodies"
  ]
}

Bodies are returned in a fixed order: Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu. Sort client-side by disposition.score or strength.rank as your view needs.

`strength` — Shadbala against what the planet needs¶

Field	Meaning
`virupa`	The Shadbala total in virupa.
`rupas`	The same total in rupas (60 virupa = 1 rupa).
`required_rupas`	What BPHS says this planet's kind needs.
`ratio`	`rupas / required_rupas`. 1.0 is classically adequate (purna); below is alpa.
`rank`	1 is the strongest planet in this chart.
`components`	The six balas that make up the total, in virupa.
`missing`	Names of any bala that could not be counted. Empty in normal operation.
`complete`	`false` while `missing` is non-empty.

Do not print a ratio while complete is false

An incomplete total is low for every planet alike, so it still ranks them correctly — but shown as an absolute figure it calls the whole chart weak. Treat complete: false as "rank only, no label". In the normal case (a chart created through this API) complete is true and missing is [].

The requirement table (BPHS), in rupas:

Planet	Required
Sun	5.0
Moon	6.0
Mars	5.0
Mercury	7.0
Jupiter	6.5
Venus	5.5
Saturn	5.0

Rahu and Ketu carry no requirement — the six balas do not rate shadow bodies — so their strength is null. That is not the same as zero, and a UI that renders it as zero will rank the nodes last in every chart. They still carry a disposition and a connection.

The six components, all in virupa:

Component	What it measures
`sthana`	Positional strength beyond uchcha: saptavargaja + ojayugma + kendradi + drekkana.
`uchcha`	Exaltation strength — distance from the debilitation point, 0…60. Also a sthana sub-bala; reported separately because it is the one a reader can check by eye.
`dig`	Directional strength — maximal in the planet's preferred angle (Sun/Mars 10th, Moon/Venus 4th, Jupiter/Mercury 1st, Saturn 7th).
`kala`	Temporal strength — paksha, vara, abda, masa, yuddha, plus nathonnatha, tribhaga and ayana from the shape of the birth day.
`chesta`	Motional strength — see the eight states.
`naisargika`	Natural ranking: Sun 60 → Saturn ≈ 8.57.
`drik`	Aspectual strength — signed sum of incoming drishti. This one can be negative, which is why a total can be lower than the sum of the parts you expected.

virupa = the sum of all seven fields above (uchcha is inside sthana conceptually but is not double-counted: sthana here is the remainder).

Sthana bala, in detail¶

Sub-bala	Max	Rule
Saptavargaja	315	The planet's housing across the seven classical divisions (D1 rasi, D2 hora, D3 drekkana, D7 saptamsa, D9 navamsa, D12 dwadashamsa, D30 trimshamsa), graded per division: mooltrikona 45, own 30, great friend 22.5, friend 15, neutral 7.5, enemy 3.75, great enemy 1.875.
Ojayugma	30	15 for an agreeable sign and 15 for an agreeable navamsa. The Moon and Venus want even signs; every other rated planet wants odd.
Kendradi	60	Kendra (1/4/7/10) 60, panaphara (2/5/8/11) 30, apoklima (3/6/9/12) 15.
Drekkana	15	15 when a planet sits in the third of the sign that suits it: male (Sun, Mars, Jupiter) first, hermaphrodite (Mercury, Saturn) second, female (Moon, Venus) third.

The friend/enemy tiers in saptavargaja are the five-fold relationship (panchadha maitri): the permanent friendship table combined with the temporary one, where whoever occupies the 2nd, 3rd, 4th, 10th, 11th or 12th from a planet is a temporary friend and the 1st, 5th, 6th, 7th, 8th and 9th are temporary enemies.

Permanent	+ temporary friend	+ temporary enemy
friend	great friend	neutral
neutral	friend	enemy
enemy	neutral	great enemy

The divisions are the Parashari ones, not the generic sign-by-sign walk: an odd sign's first hora belongs to the Sun and its second to the Moon (reversed in an even sign); the drekkana thirds are the sign, the 5th from it and the 9th; an odd sign's saptamsa counts from itself and an even sign's from its opposite; the trimshamsa is five unequal arcs owned by Mars, Saturn, Jupiter, Mercury and Venus, reversed in an even sign.

Chesta bala: the eight states of motion¶

A planet is strongest when it is doing something unusual. The state is read from the planet's true speed against its mean daily motion.

State	Virupa	What it is
`vakra`	60	Retrograde
`atichara`	45	Much faster than mean (> 1.5×)
`anuvakra`	30	Retrograde back into the previous sign
`sama`	30	At the mean rate (± 10%)
`chara`	30	Faster than mean
`vikala`	15	Stationary (< 5% of mean)
`manda`	15	Slower than mean
`mandatara`	7.5	Much slower than mean (< 50%)

The Sun and the Moon never turn retrograde, so BPHS gives them substitutes: the Sun's chesta bala is its ayana bala and the Moon's is its paksha bala. Both are also counted inside kala bala — the classical text counts them twice on purpose, and this follows the text.

`disposition` — how benefic the planet is for this lagna¶

Five voices, each bounded in −1 … +1, each with a weight and a stated reason. The score is their weighted mean, so it is bounded too. Every term is returned, including the ones that said nothing, so a UI can show which voice carried the answer.

Term	Weight	What it looks at
`functional_nature`	0.30	The planet's role for this ascendant: yogakaraka +1.0, functional benefic +0.6, lagnesha +0.5, neutral 0.0, functional malefic −0.6.
`dignity`	0.25	Its standing in the sign it occupies: exaltation +1.0, mooltrikona +0.8, own +0.6, great friend +0.4, friend +0.2, neutral 0.0, enemy −0.4, great enemy −0.6, debilitation −1.0.
`house`	0.20	The house from the lagna: 9th +1.0, 5th +0.8, 1st and 10th +0.6, 4th and 7th +0.4, 3rd and 11th +0.3, 2nd 0.0, 6th −0.5, 12th −0.6, 8th −0.8.
`association`	0.15	The share of the connection reaching the planet that comes from its friends, rescaled to −1 … +1. A share, never a sum: a sum would make the score depend on how many malefics exist at all.
`condition`	0.10	Combustion (−1.0, within the planet's own orb: Mercury 5°, Venus 10°, Jupiter 11°, Saturn 15°, Mars 17°), papakartari — hemmed by malefics on both sides (−0.5), retrogression (± 0.2: a benefic gains voice, a malefic gains obstinacy).

Functional, not natural

Saturn is a yogakaraka for a Libra lagna and a hard planet for a Cancer one. A permanent benefic/malefic table cannot say that. Change nothing but the ascendant and this score moves — that is the point of it.

Bands (disposition.band):

Score	Band
≥ 0.5	`very_benefic`
≥ 0.15	`benefic`
> −0.15	`mixed`
> −0.5	`difficult`
≤ −0.5	`very_difficult`

Rahu and Ketu are rated on all five voices except dignity — they own no sign, so the dignity term abstains with weight: 0.0 and the reason "no dignity is defined for this body". An abstaining term keeps the remaining weights in proportion; it does not drag the score to zero.

Worked example, from the Sun in the response above:

functional_nature  −0.6   × 0.30  = −0.180   (malefic for a gemini lagna)
dignity            +0.2   × 0.25  = +0.050   (in a friend's sign)
house              +0.6   × 0.20  = +0.120   (1st from the lagna)
association        +0.598 × 0.15  = +0.090   (80% of what reaches it is friendly)
condition           0.0   × 0.10  =  0.000   (unafflicted)
                                    ───────
                                     +0.080  → band "mixed"

A strong planet (ratio 1.95, rank 1) that is only mildly helpful — exactly the pairing a single collapsed number cannot express.

`connection` — how tied the body is to the chart¶

received is the total strength of every tie reaching the body; given is the total it sends out. Both are unsigned magnitudes, never verdicts. The individual ties are listed by /influence-network.

`GET /v1/vedic/charts/{id}/theo/houses`¶

How much of the chart's power falls in each house, and whether it lands well.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.astrolinkers.com/v1/vedic/charts/$CHART/theo/houses"

{
  "chart_id": "019febf3-2900-7542-9982-f00048b6da70",
  "method_version": "theo-strength-disposition-v2",
  "houses": [
    {
      "house_number": 1,
      "sign": "gemini",
      "occupants": ["sun", "jupiter"],
      "weighted": 2303.02,
      "share": 0.1175,
      "support": 0.011
    },
    {
      "house_number": 2,
      "sign": "cancer",
      "occupants": ["ketu"],
      "weighted": 1464.72,
      "share": 0.0747,
      "support": 0.758
    },
    "…10 more houses"
  ]
}

Field	Meaning
`weighted`	Σ (each planet's rupas × its connection to the house). Raw, for auditing.
`share`	That house's share of the chart's total power. The twelve sum to 1.0, so `0.0833` is an average house.
`support`	−1 … +1 — the share of the connection reaching the house that this lagna calls benefic.

Power and support are different questions, and a busy 8th house is powerful and hard. Read share for "how much happens in this area of life" and support for "does it land well". A planet with no Shadbala requirement (a node) lends connection but no weight — it is not rated on the six balas, so it cannot be weighted by them.

Migration from `net_strength`¶

Before theo-strength-disposition-v1, /influence-network published a signed net_strength per planet, and /theo/sign-influences published net_strength, benefic_strength and malefic_strength per sign. Those fields are gone.

They were an artefact rather than a reading. The number summed a static benefic/malefic polarity over every other planet; because a planet does not influence itself and the polarity table holds four benefics against five malefics, the four natural benefics scored worst in 82% of charts by arithmetic alone. It measured the table, not the chart.

Old field	Replacement
`planet_summaries[].net_strength`	`disposition.score` + `disposition.band` on `/theo/planets` for the verdict; `connection.received` on the same endpoint for the magnitude.
`by_sign[].net_strength`	`support` on `/theo/sign-influences`.
`by_sign[].benefic_strength` / `malefic_strength`	`connection` (the unsigned total) + `support` (the balance) on the same endpoint.
"planet strength" read off `net_strength`	`strength.ratio` on `/theo/planets` — an actual Shadbala.

If your integration ranked planets by net_strength, the closest honest replacements are disposition.score (for "who helps this person") and strength.rank (for "who can act"). They answer different questions, and picking the right one is the migration.

Theo: planet strength & disposition¶

GET /v1/vedic/charts/{id}/theo/planets¶

strength — Shadbala against what the planet needs¶

Sthana bala, in detail¶

Chesta bala: the eight states of motion¶

disposition — how benefic the planet is for this lagna¶

connection — how tied the body is to the chart¶

GET /v1/vedic/charts/{id}/theo/houses¶

Migration from net_strength¶