Natal Insights & Interpretation Logic

What is the Natal Insights endpoint?

You need a high-level snapshot of a chart's overall flavor without parsing every planet position yourself. The Natal Insights endpoint takes birth data and returns three structured summaries: element distribution (Fire, Earth, Air, Water percentages), mode balance (Cardinal, Fixed, Mutable), and hemisphere dominance (east-west and north-south). Each block ships with an interpretive paragraph.

This endpoint is part of the Natal Chart API.

Why does this endpoint exist?

You are building a personality overview UI and you need the chart's "big picture" tendencies, not every planet detail. Computing element distribution means tallying which sign each of the sixteen natal points falls in, then weighting and summing. Mode balance and hemisphere dominance follow the same shape with different groupings. This endpoint runs all three aggregations in one call and bundles each with reader-facing prose.

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. Hemisphere dominance depends on house placement, so birth time precision affects the east-west and north-south splits more than the element or mode tallies. Authentication uses a Bearer token in the Authorization header.

What does the response data look like?

You get a data object with three top-level blocks: elements, modes, and hemisphere. Each block carries the underlying breakdown plus a description tied to the dominant value. The hemisphere block has two sub-objects (east_west and north_south) since hemispheres are measured on both axes.

The percentages in each breakdown sum to 100, ready for a pie chart, stacked bar, or progress-bar set.

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). The element split is Water-dominant (41.67%), modes are Cardinal-led (50%), and hemispheres lean West and South. Description fields are truncated for readability.

{
  "success": 1,
  "data": {
    "elements": {
      "elements_data": [
        { "name": "Fire", "percentage": 8.33 },
        { "name": "Earth", "percentage": 16.67 },
        { "name": "Air", "percentage": 33.33 },
        { "name": "Water", "percentage": 41.67 }
      ],
      "description": "You're deeply intuitive and emotionally aware. You feel things intensely... (truncated)"
    },
    "modes": {
      "modes_data": [
        { "name": "Cardinal", "percentage": 50 },
        { "name": "Fixed", "percentage": 25 },
        { "name": "Mutable", "percentage": 25 }
      ],
      "description": "You're a natural initiator which makes it natural for you to start things... (truncated)"
    },
    "hemisphere": {
      "east_west": {
        "dominant": "West",
        "description": "Your western hemisphere is dominant, you're naturally collaborative... (truncated)"
      },
      "north_south": {
        "dominant": "South",
        "description": "As you're Southern-dominant, you're extroverted, socially engaged... (truncated)"
      }
    }
  }
}

What can you build with this endpoint?

You use Natal Insights whenever your product surfaces "big picture" personality content rather than per-planet detail. The structured percentages and descriptions map cleanly to dashboard cards, onboarding screens, and social-share graphics.

1. Personality dashboard cards. Show three side-by-side cards (Elements, Modes, Hemispheres) with progress bars or pie charts driven by the percentages.
2. Onboarding "your astrology snapshot" screen. Surface the dominant element, mode, and hemisphere on the first profile screen for instant personalization.
3. Social-share images. Render the percentages into a branded graphic users can share, with the dominant tendency as the headline.
4. Compatibility comparisons. Call the endpoint for two charts side by side to surface element-and-mode complementarity in relationship UI.

How accurate is the calculation?

You are computing percentage distributions across sixteen natal points (Sun, Moon, planets, nodes, Chiron, Ascendant, Midheaven, Part of Fortune, Lilith). Position calculations come from Swiss Ephemeris with NASA JPL ephemeris data. The element and mode tallies depend only on which sign each point falls in, so they are stable against small birth-time errors.

Hemisphere dominance depends on the house placement of each body, which means the house_system you choose can shift the east-west and north-south splits. Default is Placidus. Birth time precision matters here: a 30-minute time error can move bodies near house cusps to the other hemisphere.

How does this relate to the parent API?

You are surfacing a high-level personality summary on top of the standard birth chart. This endpoint complements the Natal Chart API by providing pre-computed element, mode, and hemisphere distributions with interpretive copy.

Planetary Positions returns each body's element and modality individually, so you could compute these distributions client-side. This endpoint saves that work and adds the prose layer in twelve languages. Use it when your UI needs the snapshot view; use Planetary Positions when you need per-body detail.

Summary

The Natal Insights endpoint returns element distribution, mode balance, and hemisphere dominance for any birth, each with an interpretive description. The percentages map directly to chart components, and the descriptions ship in twelve languages. Use it whenever your product needs a "big picture" personality overview without per-planet drill-down.