Dominant Planets & Elements

What is the Dominants endpoint?

You need a weighted ranking of which planets and elements drive a chart, not just where each body sits. The Dominants endpoint takes birth data plus a calculation method and returns three blocks: ranked dominant planets with weighted scores, an element distribution table with sub-breakdowns, and a derived signature sign combining the dominant element with the dominant modality.

This endpoint is part of the Natal Chart API.

Why does this endpoint exist?

You are surfacing high-level chart character and you want planets ranked by influence, not listed equally. A planet's dominance depends on multiple weighted inputs: sign, house, angularity, rulership, and aspect count. Aggregating those weights across all bodies takes work. This endpoint runs the calculation and returns ranked, percentage-normalized scores.

What inputs does it need?

You pass standard birth data plus a method parameter that selects which weighting rules to apply. The endpoint computes the dominant planets, the dominant element, and the signature sign all in one call. Authentication uses a Bearer token in the Authorization header.

What does the response data look like?

You get an envelope with status, code, message, and data. The data object splits into three blocks: dominant_planets ranks each planet by weighted score; dominant_element returns per-element breakdowns plus the overall dominant; signature_sign derives a signature sign from element-and-modality counts.

What does a real response look like?

Below is a slice of the response for a sample birth (24 May 2023, 14:40:43 IST, New Delhi). Moon ranks as the dominant planet, Water is the dominant element at 36%, and the signature sign is Scorpio.

{
  "status": "success",
  "code": 200,
  "message": "Request successful",
  "data": {
    "dominant_planets": [
      { "planet_name": "Moon", "sign": 6, "house": 2, "angle": 0, "ruler": 3, "aspects": 6, "total": 17, "percent": "22.08", "rank": 1 },
      { "planet_name": "Mars", "sign": 4, "house": 2, "angle": 0, "ruler": 0, "aspects": 6, "total": 12, "percent": "15.58", "rank": 2 },
      { "planet_name": "Sun", "sign": 3, "house": 0, "angle": 0, "ruler": 1, "aspects": 7, "total": 11, "percent": "14.29", "rank": 3 }
    ],
    "dominant_element": {
      "table": {
        "Fire":  { "sun_moon_asc": 0, "personal": 2, "dominant": 2, "sum": 4, "percent": "16%" },
        "Earth": { "sun_moon_asc": 0, "personal": 4, "dominant": 0, "sum": 4, "percent": "16%" },
        "Air":   { "sun_moon_asc": 6, "personal": 0, "dominant": 2, "sum": 8, "percent": "32%" },
        "Water": { "sun_moon_asc": 3, "personal": 4, "dominant": 2, "sum": 9, "percent": "36%" }
      },
      "dominant": "Water"
    },
    "signature_sign": {
      "element_counts": { "Fire": 1, "Earth": 2, "Air": 1, "Water": 3 },
      "modality_counts": { "Cardinal": 2, "Fixed": 3, "Mutable": 2 },
      "signature": "Water + Fixed",
      "sign": "Scorpio"
    }
  }
}

What can you build with this endpoint?

You use Dominants whenever your product needs ranked planet influence or a single-sign signature rather than an even per-planet listing. The three response blocks each map to a different UI pattern: ranked planet cards, element-balance graphs, and a single signature-sign feature.

1. Top-3 dominant-planet card. Render the three highest-ranked planets with their percentage scores as a "what drives your chart" panel.
2. Element-balance dashboard. Use the per-element percentages to power a stacked-bar or pie chart showing how Fire, Earth, Air, and Water weight in the chart.
3. Signature-sign feature. Surface the derived signature sign (Scorpio in our example) as a "your astrological signature" element distinct from Sun, Moon, and Ascendant.
4. Personality archetype matching. Use the dominant planet plus signature sign to drive archetype content (e.g. "Moon-dominant Scorpio signature" themed reading).

How accurate is the calculation?

You are running weighted scoring across multiple chart features. The underlying positions, signs, and houses come from Swiss Ephemeris with NASA JPL ephemeris data. The weighting itself follows the chosen method, so results stay reproducible across calls with the same inputs.

The element breakdown surfaces sub-counts (sun_moon_asc, personal, dominant) so you can verify how each total adds up. On balanced charts, surface the percentages alongside the rank so users see the closeness rather than just the winner.

How does this relate to the parent API?

You are layering ranked influence on top of the standard chart. This endpoint complements the Natal Chart API by returning weighted dominants that the per-body Planetary Positions endpoint does not surface.

Planetary Positions returns each body equally weighted; Natal Insights gives raw element percentages without per-planet ranking; this endpoint adds the influence math. Combine all three for a full picture: positions for the data, insights for distribution overview, dominants for ranked emphasis.

Summary

The Dominants endpoint returns ranked dominant planets, a detailed element distribution, and a derived signature sign for any birth chart. It runs on Swiss Ephemeris with NASA JPL data and applies the weighting method you select. Use it for influence-ranked planet cards, element-balance dashboards, signature-sign features, and any UI surfacing chart character as ranked rather than listed.