Skip to content
POST/api/astro/planet_insights/1 credit

Planet placement readings

Prewritten interpretations for a single planet in a single position. Give it a planet and where that planet sits — a zodiac sign, a house, or a nakshatra — and it returns the classical reading for that combination. It is a lookup into a text corpus, not a calculation: no date, time or place is involved, and the same request always returns the same text. Use it to caption a chart you have already computed. Take Jupiter's sign, house and nakshatra from `/api/astro/chart/`, then call this endpoint for the wording. All three keys can be requested in one call, but each has its own extra parameter, so `planet`, `sign`, `house` and `nakshatra` must all be present in the body when you ask for all three. Coverage is nine planets (the seven plus Rahu and Ketu) across twelve signs and twelve houses. Nakshatra readings exist for the seven classical planets only — Rahu and Ketu have none. An unrecognised planet, sign, house or nakshatra comes back as an explanatory string with HTTP 200 rather than an error, so check what type you were given before rendering it.

https://yogataraapi.prahlad.app/api/astro/planet_insights/
Test Request

Authentication

Send your key in the X-API-Key header. Keys are server-side credentials — never put one in browser JavaScript or a mobile app.

X-API-Key: yt_live_a1b2c3d4_…
Content-Type: application/json

Request fields

FieldTypeRequiredNotes
houseintegerrequired
keysarrayrequired

Which calculations to return, as a list of names. See the key table for this endpoint; an unrecognised name rejects the whole request. One call costs one credit however many keys you ask for, so request everything you need at once rather than making several calls.

nakshatrastringrequired
ashwinibharanikrittikarohinimrigasiraaardrapunarvasupushyamiaasreshamakhapoorva phalguniuttara phalguni

The list above is the one used by jupiter, mercury, venus and saturn. 'rahu' and 'ketu' have no nakshatra data at all. Unmatched values return "Invalid nakshatra: <x> for planet <p>" with HTTP 200.

planetstringrequired
sunmoonmarsmercuryjupitervenussaturnrahuketu

An unknown planet returns the string "Invalid planet: <x>" with HTTP 200, not an error status. Note rahu and ketu have NO nakshatra data (insights['rahu']['nakshatras'] is None), so get_planet_nakshatra_insight returns "No nakshatra data available for rahu".

signstringrequired
ariestaurusgeminicancerleovirgolibrascorpiosagittariuscapricornaquariuspisces

DATA BUG worth documenting: for planet='sun' the key is misspelled 'vigro' instead of 'virgo', so sun+virgo returns "Invalid sign: virgo for planet sun" while sun+vigro works. All eight other planets use 'virgo'.

Available keys (3)

Ask for exactly the calculations you want by listing them in keys. An unknown key rejects the whole request, and you are charged 1 credit however many you ask for — so batch them.

KeyExtra fields neededDescription
get_planet_house_insightplanet, houseThe reading for `planet` placed in a house, `house` being 1 to 12. Returns an object with the house label, a summary and trait lists, plus `classicalTexts` — a list of `{heading, text}` quoting Parashara, Brihat Jataka, Saravali and Phaladipika on that placement — and `houseLordVariations`, a list of `{ascendent, aspect, result}` giving how the reading changes for each of the twelve ascendants. Some of the summary and trait fields are null where only the classical quotations exist.
get_planet_nakshatra_insightplanet, nakshatraThe reading for `planet` placed in `nakshatra`, returned as a single sentence or two of plain text rather than a structured object. Available for the seven classical planets across all 27 nakshatras; Rahu and Ketu have no nakshatra readings and return an explanatory string instead.
get_planet_sign_insightplanet, signThe reading for `planet` placed in `sign`. Returns an object with `sign` (the Sanskrit label for the combination, such as "Mesa Brhaspati"), a `summary` paragraph, and the lists `core traits`, `psychologicalPhysicalTraits`, `astrologicalReasoning` and `drstiphala`, the last covering the effects of that planet's aspects from there. Note the space in the `core traits` field name.

Example request

curl -X POST https://yogataraapi.prahlad.app/api/astro/planet_insights/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keys":["get_planet_sign_insight"],"planet":"Jupiter","sign":"aries","house":0,"nakshatra":"rohini"}'

Response

{
  "data": {
    "get_planet_sign_insight": {
      "sign": "Mesa Brhaspati",
      "summary": "Jupiter in Aries produces a bold, authoritative, and resourceful individual with strong leadership capabilities. Aries is ruled by Mars (Maṅgala), a planet friendly to Jupiter and symbolizing courage, initiative, and battle-readiness. Jupiter here gains the spirit of a warrior-sage, combining spiritual strength with physical initiative. The placement enhances fame, wealth, power, and generational prosperity, especially through sons. However, the position also introduces difficulties like enemies, physical injuries, and excessive expenditures due to Aries being the debilitation sign for Saturn (Śani), whose tamasic qualities interfere with Jupiter's sattvic nature. The individual is splendorous, generous, and powerful, but also faces trials that temper their greatness",
      "core traits": [
        "Argumentative in disposition",
        "Acquiring precious stones and ornaments through effort",
        "Endowed with strength, sons, and wealth",
        "Eminent and famous profession",
        "Splendorous",
        "Many enemies",
        "Many expenses",
        "Injured body",
        "Confers severe and cruel punishments"
      ],
      "psychologicalPhysicalTraits": [
        "Argumentative in disposition",
        "Acquiring precious stones and ornaments through effort",
        "Endowed with strength, sons, and wealth",
        "Eminent and famous profession",
        "Splendorous",
        "Many enemies",
        "Many expenses",
        "Injured body",
        "Confers severe and cruel punishments",
        "Love of grandeur",
        "Powerful",
        "Wealthy",
        "Prudent",
        "Many children",
        "Courteous",
        "Generous",
        "Firm",
        "Sympathetic",
        "Happy marriage",
        "Patient nature",
        "Harmonious",
        "Refined",
        "High position"
      ],
      "astrologicalReasoning": [
        {
          "heading": "Initiative & Argumentation",
          "text": "Meṣa is ruled by Maṅgala, the god of war and action, endowing Jupiter with a strong fighting disposition and argumentative temperament."
        },
        {
          "heading": "Wealth & Luxuries",
          "text": "Sūrya, exalted in Meṣa, governs precious metals and gemstones. Jupiter, the Dhanakāraka, placed here results in acquiring valuables through effort."
        },
        {
          "heading": "Progeny & Strength",
          "text": "Meṣa is a masculine sign ruled by male planets (Sūrya and Maṅgala). Jupiter, as the Santana Kāraka, gains support here, indicating sons, strength, and vitality."
        },
        {
          "heading": "Fame & Eminence",
          "text": "As the 1st house of Kālapuruṣa, Aries governs fame. Jupiter's placement brings name, professional eminence, and public recognition."
        },
        {
          "heading": "Drawbacks of the Sign",
          "text": "Meṣa is Śani's debilitation sign. Jupiter here absorbs Śani's weaknesses, causing a rise in enemies (6H), injury-proneness, emotional detachment (due to 8H being Moon's debilitation), and heavy expenditure (12H effects)."
        },
        {
          "heading": "Judgement & Harshness",
          "text": "With Jupiter reflecting Maṅgala's and Śani's stern traits, the native may confer harsh or severe judgments lacking emotional nuance."
        }
      ],
      "drstiphala": [
        {
          "planet": "Sūrya",
          "aspect": "positive",
          "result": "Charitable, truthful, famous sons, highly fortunate, abundant hair on the body."
        },
        {
          "planet": "Candra",
          "aspect": "positive",
          "result": "Charitable, truthful, famous sons, highly fortunate, abundant hair on the body."
        },
        {
          "planet": "Maṅgala",
          "aspect": "positive",
          "result": "Belonging to a royal dynasty, fearless, fierce, endowed with political knowledge, modest, affluent, has a disobedient wife and disobedient servants."
        },
        {
          "planet": "Budha",
          "aspect": "negative",
          "result": "Liar, crafty, sinful, skilful in detecting others' flaws, serves others, grateful, modest, not outspoken."
        },
        {
          "planet": "Śukra",
          "aspect": "positive",
          "result": "Very happy with residences, sleeping comforts, robes, perfumes, garlands, ornaments, wife, very timid."
        },
        {
          "planet": "Śani",
          "aspect": "mixed",
          "result": "Talkative, eloquent, devoid of happiness, brilliant, has mean children and a mean wife."
        }
      ]
    }
  },
  "status": 200,
  "is_error": false,
  "message": "successful"
}

Captured from a real call using the exact request above. Results sit under data, keyed by what you requested.

Errors

Metering errors return { "error": "…", "message": "<code>", "is_error": true }. Show error to people and branch on message. See the error reference.