Retrograde and combust planets via astrology API

Q: How do I detect retrograde planets through the API?

Call POST /v2/astrology/planets with the birth datetime, latitude, longitude, and timezone. Each planet in the response includes a signed speed and an isRetrograde boolean; a negative speed corresponds to retrograde motion.

Q: Does the API tell me if a planet is combust?

Yes. Each planet entry includes an isCombust flag and a combustionOrb value (angular distance to the Sun). The flag applies the correct per-planet, direction-aware orb, so you branch on it rather than recomputing combustion from a single flat threshold.

Q: Can I get a written interpretation instead of raw flags?

Yes. Post a natural-language question to POST /api/v1/astrology/query with birth details nested under birthDetails. The response explains the conditions with reasoning traced to classical sources, and declines to invent meaning where no clean classical basis exists.

To detect retrograde and combust planets through the Vedika Intelligence API, send a birth chart to the V2 computation layer at /v2/astrology/* or ask a natural-language question at POST /api/v1/astrology/query. Every planetary position the API returns carries motion state (retrograde or direct) and combustion status relative to the Sun, computed by the XALEN Ephemeris and grounded in classical rules for interpretation. This guide shows the exact request shapes, the math behind the flags, and how to surface these conditions in product features without inventing meaning the chart does not support.

What retrograde and combustion mean in a chart

Retrograde motion (vakri in Jyotish) is the apparent backward drift of a planet against the zodiac as seen from Earth — a geometric illusion produced by the relative orbital speeds of Earth and the planet. The Sun and Moon never go retrograde; Mercury, Venus, Mars, Jupiter, and Saturn do, and the lunar nodes Rahu and Ketu are always retrograde by convention. Combustion (asta) is a separate condition: a planet sitting too close to the Sun in longitude is said to be "burnt," its significations dimmed by proximity to the solar beams.

These two states are independent — a planet can be retrograde and combust at once, either alone, or neither. Because both are derived purely from positional geometry, they are deterministic outputs of an ephemeris, not interpretive guesses. That distinction matters when you build features: the flags are astronomy, while the meaning attached to them is astrology drawn from classical texts.

Why the orb threshold is not one number

Classical Jyotish does not use a single combustion orb for every planet. Brihat Parashara Hora Shastra and later compendia assign different angular distances to each planet, and the threshold can differ further when the planet itself is retrograde. Mercury and Venus, which never stray far from the Sun, carry tighter and direction-dependent orbs; the outer planets use wider ones. The API encodes these per-planet thresholds so you do not have to hardcode a flat value that would misclassify Mercury combustion in roughly the cases that matter most.

Reading the flags from a computed chart

The V2 computation endpoints return a flat birth payload and a planet array where each entry includes its longitude, sign, house, speed, and the motion and combustion flags. A negative longitudinal speed indicates retrograde motion; the combustion flag reflects the per-planet orb comparison against the Sun.

curl -X POST https://api.vedika.io/v2/astrology/planets \
  -H "x-api-key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1988-04-17T10:30:00",
    "latitude": 18.5204,
    "longitude": 73.8567,
    "timezone": "Asia/Kolkata",
    "system": "vedic"
  }'

A representative planet entry in the response carries the fields you need to branch on:

// one element of the planets[] array
{
  "name": "Mercury",
  "longitude": 24.13,        // degrees in sign
  "sign": "Aries",
  "house": 7,
  "speed": -0.42,            // negative => retrograde
  "isRetrograde": true,
  "isCombust": true,         // within Mercury's per-planet orb of the Sun
  "combustionOrb": 3.1       // angular distance to the Sun, in degrees
}

Deriving your own UI badges from this is a few lines. Note that you should trust the API's isCombust flag rather than recomputing it from combustionOrb with a flat threshold, since the correct threshold is planet- and direction-specific.

const res = await fetch("https://api.vedika.io/v2/astrology/planets", {
  method: "POST",
  headers: {
    "x-api-key": process.env.VEDIKA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    datetime: "1988-04-17T10:30:00",
    latitude: 18.5204,
    longitude: 73.8567,
    timezone: "Asia/Kolkata",
    system: "vedic",
  }),
});

const { planets } = await res.json();

const retrograde = planets.filter((p) => p.isRetrograde).map((p) => p.name);
const combust = planets.filter((p) => p.isCombust).map((p) => p.name);

console.log("Retrograde:", retrograde); // e.g. ["Mercury", "Saturn"]
console.log("Combust:", combust);       // e.g. ["Mercury"]

Asking for interpretation in natural language

If you want a written reading rather than raw flags, post the question to the AI query endpoint. Send the birth details once and let Vedika AI assemble the chart, detect the conditions, and explain them with sourced reasoning. The birth block here is nested under birthDetails, which differs from the flat V2 shape.

import os, requests

resp = requests.post(
    "https://api.vedika.io/api/v1/astrology/query",
    headers={"x-api-key": os.environ["VEDIKA_API_KEY"]},
    json={
        "question": "Which planets in my chart are retrograde or combust, and what does that mean for me?",
        "birthDetails": {
            "datetime": "1988-04-17T10:30:00",
            "latitude": 18.5204,
            "longitude": 73.8567,
            "timezone": "Asia/Kolkata",
        },
        "speed": "fast",
    },
)

print(resp.json()["answer"])

For chat-style products where you want tokens to stream as they are generated, call /api/v1/astrology/query/stream instead — it returns Server-Sent Events with the same request body. The optional "speed": "fast" field routes to Vedika Swift for lower latency when you do not need the deepest reasoning pass.

Keeping the interpretation honest

The reason to let the API write the reading rather than your own prompt is grounding. Statements about what a combust Mercury or a retrograde Saturn signifies are traced to classical sources actually taught in Jyotish and KP curricula — Brihat Parashara Hora Shastra, Phaladeepika, Saravali, Jataka Parijata — rather than paraphrased from web summaries. If a placement has no clean classical basis, the response says so instead of fabricating a verse. That restraint is the difference between a feature you can put in front of paying users and one that invites a correction the first time a domain expert reads it.

Three systems, three sets of rules

Retrograde motion is identical across traditions because it is pure astronomy — the planet's heliocentric geometry does not care which zodiac you overlay. Combustion interpretation and the surrounding chart context, however, diverge. The same API serves all three systems from one request by switching the system field.

System	Zodiac	Retrograde flag	Combustion handling
Vedic	Sidereal	From speed sign	Per-planet orbs, direction-aware (BPHS tradition)
Western	Tropical	From speed sign	Cazimi / combust / under-beams gradations (Tetrabiblos lineage)
KP	Sidereal	From speed sign	Read with sub-lord and significator context

Because the underlying positions come from one engine, a Vedic and a Western query for the same birth agree on which planets are retrograde and on the raw Sun–planet separation; they differ only where the tradition's interpretive rules differ. That consistency is hard to get when you stitch together separate vendors for each system.

Why the ephemeris layer matters here

Retrograde and combustion are threshold conditions, which makes them sensitive to small positional errors. A planet a fraction of a degree from a combustion boundary, or near a retrograde station where its speed crosses zero, can flip classification if the longitude is even slightly off. Vedika's positions are produced by the XALEN Ephemeris, an open-source astronomical engine (Apache-2.0, published to crates.io, PyPI, and as a WebAssembly package) that is validated against JPL DE440 and the reference swetest output. Across a large randomized test of millions of charts, no planetary longitude deviated beyond a tenth of a degree from the reference.

This is ephemeris precision — astronomical position accuracy — not a claim about the correctness of any astrological interpretation. But it is exactly the property you want at the boundaries, because it means the retrograde and combust flags do not jitter from numerical noise. If you need to verify a value, the engine is open source and the sandbox lets you compare without spending a credit.

Key facts

Retrograde is detected from longitudinal speed: a negative speed means the planet is moving backward through the zodiac.
Sun and Moon are never retrograde; Rahu and Ketu are retrograde by convention.
Combustion uses per-planet orbs that differ by planet and, for inner planets, by retrograde direction — not a single flat threshold.
Compute flags via POST /v2/astrology/* (flat datetime/latitude/longitude/timezone); get written readings via POST /api/v1/astrology/query (nested birthDetails).
Streaming readings come from /api/v1/astrology/query/stream over Server-Sent Events.
Authenticate with the header x-api-key: vk_live_*; the base URL is https://api.vedika.io.
One API covers Vedic, Western, and KP via the system field, plus 700+ operations across 25 domains and 30 languages.
Positions come from the XALEN Ephemeris, validated against JPL DE440 and swetest; interpretation is grounded in classical texts under a no-bluffing citation policy.

Getting started

You can try every request above against the free sandbox with no API key, then move to a live key when you are ready. Single computation calls are inexpensive on a per-query basis, and the monthly plans on the pricing page start with wallet credits for Starter teams and scale up to dedicated capacity for Enterprise. Full request and response schemas for the computation and query endpoints live in the documentation. If you are building a conversational feature, the related walkthrough on streaming astrology readings over SSE pairs well with the retrograde and combustion checks shown here.

FAQ

How do I detect retrograde planets through the API?

Call POST /v2/astrology/planets with the birth datetime, latitude, longitude, and timezone. Each planet in the response includes a signed speed and an isRetrograde boolean; a negative speed corresponds to retrograde motion.

Does the API tell me if a planet is combust?

Yes. Each planet entry includes an isCombust flag and a combustionOrb value (the angular distance to the Sun). The flag applies the correct per-planet, direction-aware orb, so you should branch on it rather than recomputing combustion from a single flat threshold.

Are retrograde results the same in Vedic, Western, and KP?

The retrograde flag is identical across all three because it is pure astronomy. What differs is the interpretive treatment of combustion and surrounding context, which follows each tradition's classical rules. Switch traditions with the system field on the same request.

Can I get a written interpretation instead of raw flags?

Yes. Post a natural-language question to POST /api/v1/astrology/query with the birth details nested under birthDetails. The response explains the retrograde and combust conditions with reasoning traced to classical sources, and declines to invent meaning where no clean classical basis exists.