Chart Shape Classification

What is the Chart Shape endpoint?

You need the overall geometric shape a chart's planets form on the wheel. The Chart Shape endpoint takes birth data and returns the classification name (Bundle, Bowl, Bucket, Locomotive, Seesaw, Splash, Splay, Dual Cluster, and others) plus a pre-rendered SVG diagram showing how the planets cluster around the wheel.

This endpoint is part of the Natal Chart API.

Why does this endpoint exist?

You are surfacing high-level chart character and you want the Marc Edmund Jones shape classification without writing the geometric detection logic yourself. Detecting a Bundle (all planets within 120 degrees), a Bowl (within 180 degrees), or a Bucket (Bowl with one planet across) means measuring the angular gaps between consecutive bodies on the wheel. This endpoint handles the classification rules and returns a ready-to-display result.

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. Shape classification works on the underlying ecliptic positions, so no house_system parameter is needed. 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 carries just two fields: the classification name as a string and a rendered SVG diagram showing the planet distribution on the wheel. The SVG is large (typically 70-90 KB) since it draws the full wheel with planet glyphs.

The classification is one of the standard Marc Edmund Jones shapes plus modern variants like "Dual Cluster" for charts where bodies form two distinct groupings rather than a single recognizable shape.

What does a real response look like?

Below is the response shape for a sample birth (24 May 2023, 14:40:43 IST, New Delhi). The classification is "Dual Cluster". The svg field is truncated for readability; the live response runs about 80 KB of SVG markup.

{
  "status": "success",
  "code": 200,
  "message": "Request successful",
  "data": {
    "chart_shape": "Dual Cluster",
    "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" version=\"1.1\" width=\"705\" height=\"705\"> ...truncated, ~80 KB of SVG markup highlighting the planet distribution... </svg>"
  }
}

What can you build with this endpoint?

You use Chart Shape whenever your product surfaces high-level chart character as a single classification rather than per-planet detail. The shape name is short enough for a card title; the SVG is a finished visual you can embed directly.

1. "Your chart at a glance" cards. Show the shape name as a headline ("You have a Locomotive chart") with the SVG diagram below. Pair with prose drawn from your content layer.
2. Personality archetype features. Use the classification to drive shape-based interpretation content. A Bundle chart suggests focused energy, a Splash suggests scattered interests.
3. Onboarding signature stat. Surface the chart shape on the first profile screen alongside Sun sign, Moon sign, and Ascendant for a richer initial snapshot.
4. Comparison features. Detect when two charts share the same shape ("you both have Bowl charts") for relationship or family astrology UI.

How accurate is the calculation?

You are running geometric classification on the underlying planet positions. Position data comes from Swiss Ephemeris with NASA JPL ephemeris data, so the inputs are arc-second accurate. The classification logic applies threshold rules (Bundle: all bodies within 120 degrees, Bowl: within 180, etc.) to those positions.

Some charts sit on the boundary between two classifications. For those edge cases the endpoint picks the closest match; if the result feels ambiguous, render it alongside the SVG so users can see the geometry themselves.

How does this relate to the parent API?

You are layering chart-shape interpretation on top of the standard birth chart. This endpoint complements the Natal Chart API by classifying the overall planet distribution into one named geometric shape with a rendered diagram.

Planetary Positions returns the underlying body positions; this endpoint runs the shape-detection logic across them. The Aspect Patterns endpoint (separate cluster) detects multi-body configurations; Chart Shape detects the single overall distribution. The two pair naturally for high-level chart-character UI.

Summary

The Chart Shape endpoint returns the geometric classification of any birth chart (Bundle, Bowl, Bucket, Locomotive, Seesaw, Splash, Splay, or modern variants) plus a pre-rendered SVG diagram. It runs on Swiss Ephemeris with NASA JPL data and applies the standard Marc Edmund Jones classification rules. Use it for chart-at-a-glance cards, archetype-based interpretation, and any UI that needs a single high-level shape signature.