Planetary Positions in Natal Chart API

What is the Planetary Positions endpoint?

You need the exact location of every planet at the moment of birth. The Planetary Positions endpoint takes birth data (date, time, place) and returns sixteen celestial points - Sun, Moon, the eight planets, lunar nodes, Chiron, Midheaven, Ascendant, Part of Fortune, and Lilith - each with sign, house, element, and modality.

This endpoint is part of the Natal Chart API.

Why does this endpoint exist?

You are rendering a birth chart and you need the raw positional data. Planetary Positions is the backbone of every other Natal Chart calculation: house cusps map onto these positions, the aspect table compares them, the wheel chart visualizes them. Get the planets right, and everything downstream falls into place.

What inputs does it need?

You pass standard birth data: API key, full name, date components, time components, gender, place, decimal latitude and longitude, and timezone offset from UTC. Optional parameters control language and house system. Authentication uses a Bearer token in the Authorization header alongside the body's api_key field.

What does the response data look like?

You write your response handler once and reuse it for every body. The endpoint returns an envelope with a success flag and a data array. Each array element is a celestial body object with eleven fields covering the body's name, exact ecliptic position, sign placement, house, element, and modality. The same shape repeats for all sixteen points.

What does a real response look like?

Below is a slice of the Planetary Positions response for a sample birth (24 May 2023, 14:40:43 IST, New Delhi). The full response includes all sixteen points; this slice shows seven of them so the example stays readable.

{
  "success": 1,
  "data": [
    {
      "name": "Ascendant",
      "full_degree": "185.7194554",
      "sign": "Libra",
      "sign_no": 7,
      "longitude": "5:43:10",
      "speed": "317.7084874",
      "is_retro": "false",
      "house": 1,
      "element": "Air",
      "modality": "Cardinal"
    },
    {
      "name": "Sun",
      "full_degree": "62.9674391",
      "sign": "Gemini",
      "sign_no": 3,
      "longitude": "2:58:3",
      "speed": "0.9614368",
      "is_retro": "false",
      "house": 8,
      "element": "Air",
      "modality": "Mutable"
    },
    {
      "name": "Moon",
      "full_degree": "117.3008709",
      "sign": "Cancer",
      "sign_no": 4,
      "longitude": "27:18:3",
      "speed": "12.0107241",
      "is_retro": "false",
      "house": 10,
      "element": "Water",
      "modality": "Cardinal"
    },
    {
      "name": "Mercury",
      "full_degree": "39.0266328",
      "sign": "Taurus",
      "sign_no": 2,
      "longitude": "9:1:36",
      "speed": "0.6655785",
      "is_retro": "false",
      "house": 8,
      "element": "Earth",
      "modality": "Fixed"
    },
    {
      "name": "Venus",
      "full_degree": "107.9024129",
      "sign": "Cancer",
      "sign_no": 4,
      "longitude": "17:54:9",
      "speed": "1.0291568",
      "is_retro": "false",
      "house": 10,
      "element": "Water",
      "modality": "Cardinal"
    },
    {
      "name": "Mars",
      "full_degree": "122.1365708",
      "sign": "Leo",
      "sign_no": 5,
      "longitude": "2:8:12",
      "speed": "0.5736328",
      "is_retro": "false",
      "house": 10,
      "element": "Fire",
      "modality": "Fixed"
    },
    {
      "name": "Saturn",
      "full_degree": "336.7262736",
      "sign": "Pisces",
      "sign_no": 12,
      "longitude": "6:43:35",
      "speed": "0.0393765",
      "is_retro": "false",
      "house": 5,
      "element": "Water",
      "modality": "Mutable"
    }
  ]
}

What can you build with this endpoint?

You use Planetary Positions as the foundation for any chart-rendering, interpretation, or transit-overlay feature. Most natal chart UIs call this endpoint first, cache the result, then layer report endpoints, transit overlays, or visual chart components on top of the same positional data.

1. Wheel chart rendering. Pass each body's full_degree to your SVG renderer to plot planets around the zodiac wheel.
2. Sign-grouped reports. Group bodies by sign to power "your Sun is in Gemini" style writeups. Combine with the General Sign Report endpoint for prose interpretations.
3. House analysis. Group bodies by house to build "your Mars in the 10th" style readings.
4. Element and modality summaries. Tally the element and modality fields for personality-overview UI cards.

How accurate is the calculation?

You are quoting specific degrees and signs to your users, so accuracy matters. The Planetary Positions endpoint runs on Swiss Ephemeris, sourced from NASA JPL ephemeris data, and returns arc-second precision on every body across the supported date range. More than twenty house systems are exposed via the house_system parameter; choose Whole Sign or Equal House for births at extreme latitudes where Placidus becomes unstable near the poles.

How does this relate to the parent API?

You are stitching together a full birth chart feature, and this endpoint is where the data flow starts. This endpoint complements the Natal Chart API by providing the raw positional data every other endpoint depends on.

The Natal Chart API exposes a small set of core endpoints: Planetary Positions, House Cusps, Aspect Table, Natal Wheel Chart, and a handful of report endpoints. Planetary Positions is the foundation. House Cusps positions the houses around these positions, the Aspect Table computes pairwise relationships between them, and the wheel chart renders all three together.

Summary

The Planetary Positions endpoint returns sixteen celestial points - Sun, Moon, planets, lunar nodes, Chiron, Midheaven, Ascendant, Part of Fortune, and Lilith - with sign, house, element, and modality on each. It sits at the foundation of the Natal Chart API: every other endpoint either consumes its output or operates on the same positional data. Start here for any birth-chart feature you build.