Aspect Patterns Detection

What is the Aspect Patterns endpoint?

You need to know which named aspect configurations show up in a chart. The Aspect Patterns endpoint takes birth data and returns detected configurations across eight categories: Grand Trines, T-Squares, Yods, Kites, Cradles, Mystic Rectangles, Grand Crosses, and Stelliums. Each detection ships with the contributing planets, the underlying aspects, and a renderable SVG diagram of the pattern.

This endpoint is part of the Natal Chart API.

Why does this endpoint exist?

You are interpreting a chart and you want named patterns surfaced automatically. Each pattern has its own combinatorial rules: a Grand Trine needs three planets in the same element forming three trines; a Yod needs two quincunxes converging on a sextile apex. Iterating every triplet across twenty bodies takes time. This endpoint runs the detection logic for all eight categories in one call.

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. No house_system parameter is needed since pattern detection works on the underlying planet positions and aspects, not on house placements. 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.patterns object groups detections by category. Each category key holds an array of detected patterns; an empty array means none were found. Each detection names its planets, lists the underlying aspects, and ships with a pre-rendered SVG diagram.

What does a real response look like?

Below is one T-Square detection from the response for a sample birth (24 May 2023, 14:40:43 IST, New Delhi). The full response shows nine T-Squares, two Yods, two Cradles, one Mystic Rectangle, two Grand Crosses, and five Stelliums. SVGs are truncated.

{
  "status": "success",
  "code": 200,
  "message": "Request successful",
  "data": {
    "patterns": {
      "t_squares": [
        {
          "id": "Jupiter-Moon-Pluto",
          "patternType": "tSquare",
          "planets": ["Moon", "Pluto", "Jupiter"],
          "aspects_list": [
            { "planetOne": "Moon", "planetTwo": "Pluto", "orb": 2.95, "aspect": "Opposition" },
            { "planetOne": "Moon", "planetTwo": "Jupiter", "orb": 4.43, "aspect": "Square" },
            { "planetOne": "Jupiter", "planetTwo": "Pluto", "orb": 1.48, "aspect": "Square" }
          ],
          "image": {
            "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\"... ~9 KB of SVG markup...</svg>",
            "base64_image": "data:image/svg+xml;base64,... ~12 KB of base64-encoded SVG..."
          }
        }
      ]
    }
  }
}

What can you build with this endpoint?

You use Aspect Patterns whenever your interpretation engine needs named configurations surfaced as first-class chart features. The pre-rendered SVGs let you skip pattern-drawing logic entirely, and the structured aspects_list lets you filter detections by tightness or rank patterns by significance.

1. Pattern dashboards. Render each detected pattern as a card with its name, planets, and the bundled SVG diagram.
2. Stellium highlights. A stellium of three or more planets in one sign is the most-cited pattern in modern astrology. Surface it in onboarding or "your chart at a glance" UI.
3. Yod pages. The Yod (or "Finger of God") is high-engagement content for advanced readers. Build dedicated Yod pages with planet names and apex placement.
4. Grand Trine and Grand Cross visuals. Embed the SVGs directly into report PDFs or chart-overview pages without rendering the geometry yourself.

How accurate is the calculation?

You are running combinatorial detection across the major planets and angles. Pattern detection inherits accuracy from the underlying aspect and position data, both of which come from Swiss Ephemeris with NASA JPL ephemeris data. Each detection includes the underlying aspects with orbs, so you can filter by tightness client-side.

Default orbs follow the Aspect Table conventions. A pattern with all aspects under 3 degrees is dramatically more dominant than one with 7-degree orbs, even though both are detected.

How does this relate to the parent API?

You are layering pattern recognition on top of the standard chart. This endpoint complements the Natal Chart API by detecting eight named configurations and bundling each with a renderable diagram.

Planetary Positions returns positions; the Aspect Table returns pairwise relationships; this endpoint identifies the named configurations those aspects form. Combine the three for a complete chart-analysis pipeline.

Summary

The Aspect Patterns endpoint detects eight named configurations (Grand Trine, T-Square, Yod, Kite, Cradle, Mystic Rectangle, Grand Cross, Stellium) in any birth chart. Each ships with contributing planets, the forming aspects, and a pre-rendered SVG diagram. Use it for pattern dashboards, interpretive content, and any UI surfacing named configurations as first-class chart features.