Planets
Returns the sidereal positions of all planets for a given date, time, and geographic location — a dedicated, focused endpoint that delivers the complete planetary positions data set without the surrounding chart identifiers, panchang elements, or dasha information included in the broader astro-details endpoints.
What this API does
The Planets endpoint is purpose-built for retrieving planetary position data. Given a date, time, timezone offset, and geographic coordinates, it computes the precise sidereal longitudes and placements of all nine Vedic grahas — the seven classical planets (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn) plus the lunar nodes Rahu and Ketu — using the selected ayanamsha.
Unlike the Astro Details or Birth Details endpoints, which bundle planetary positions together with chart identifiers, panchang data, and dasha timelines, the Planets endpoint is scoped exclusively to planetary position data. This makes it the most efficient choice for use cases that need only the planetary positions — such as transit lookups, ephemeris queries, chart rendering engines that source data incrementally, or any computation pipeline that requires raw planetary longitudes as input.
The endpoint is equally applicable to natal chart computation (using a birth date and time) and to current or future planetary position lookups (using any date and time), making it versatile for both birth chart and transit analysis workflows.
What data it returns
The API returns a structured JSON response including:
- Planetary positions: For each of the nine grahas (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu) — the sidereal sign (Rashi), degree within the sign, absolute longitude, house placement (relative to the Ascendant computed from the provided coordinates), Nakshatra, Pada, and retrograde status
- Ascendant (Lagna): The rising sign and degree computed from the provided date, time, and geographic coordinates, used as the reference point for house placement of each planet
- House placements: The house number (1–12) each planet occupies relative to the computed Ascendant
- Retrograde indicators: A flag for each planet indicating whether it is in retrograde motion at the specified date and time
- Nakshatra and Pada: The lunar mansion and quarter occupied by each planet, enabling Nakshatra-level analysis for any planet, not just the Moon
Main use cases
- Transit position lookups where the current or future positions of all planets are needed to assess transits over a natal chart, identify significant planetary ingresses, or generate a transit calendar
- Ephemeris and planetary almanac features in astrology apps that display daily, weekly, or monthly planetary positions for general reference or content generation
- Chart rendering engines that source planetary position data independently and combine it with separately fetched house or chart structure data to render a Kundali or chart wheel
- Yoga detection and analysis that requires the positions of all planets to identify classical planetary combinations (yogas) in a birth chart or at a given moment in time
- Transit-to-natal overlay analysis where the current planetary positions are fetched and overlaid on a stored natal chart to identify active transits and their house placements
- Incremental or modular API integrations that fetch only the data they need — using the Planets endpoint for positions and separate endpoints for panchang, dasha, or other chart components — to minimize response payload and processing overhead
- Ashtakavarga and Shadbala input preparation for custom computation pipelines that require raw planetary positions as the starting point for their own strength calculations
- Research and astronomical reference for applications that use Vedic sidereal planetary positions for astronomical study, historical chart reconstruction, or comparative ayanamsha analysis
Key functionality
- Dedicated planetary positions endpoint: Scoped exclusively to planetary position data, with no bundled panchang, dasha, or chart identifier information — delivering a clean, focused response optimized for position-only use cases.
- All nine grahas in one request: Returns positions for all seven classical planets plus Rahu and Ketu in a single API call, covering the complete set of Vedic grahas.
- Nakshatra and Pada for every planet: Provides Nakshatra and Pada data for all nine grahas, not just the Moon — enabling Nakshatra-level analysis across the entire chart for features such as Nakshatra-based yogas, transit Nakshatra tracking, or Nakshatra dasha lord identification.
- Retrograde status for all planets: Returns a retrograde flag for each planet, immediately usable for retrograde-aware chart analysis, transit alerts, and report generation.
- Dual use for natal and transit positions: Accepts any date and time, making the endpoint equally applicable to natal chart computation and to current, past, or future planetary position lookups for transit analysis.
- Ascendant and house placement included: Computes the Ascendant from the provided coordinates and returns each planet's house placement relative to it, enabling house-based analysis without a separate chart structure request.
- Ayanamsha selection: The
X-Ayanamsha header allows selection of the sidereal calculation system (e.g., Lahiri, Raman, KP), ensuring planetary positions are computed according to the practitioner's or platform's preferred Vedic tradition.
- Geographic coordinate support: Uses latitude and longitude for precise Ascendant and house cusp calculation, ensuring accuracy for any location worldwide.
- Multilingual support: The
Accept-Language header enables localized planet names, sign names, and Nakshatra names in the response, making the API suitable for a global, multilingual user base.
