GET /v1/patterns — Detect T-squares, grand trines, yods, kites, grand crosses, mystic rectangles, and stellia.

Aspect Patterns

Detect multi-body aspect configurations at a given moment. The response carries both the patterns and the aspect list they were assembled from, so every aspect inside a pattern is one the request actually detected — with the orb that admitted it.

Text

GET  /v1/patterns
POST /v1/patterns

Credit cost: 1

The same detection is available inside any chart response by adding patterns=true to /v1/natal-chart, /v1/synastry, /v1/davison, /v1/progressed, /v1/draconic, or /v1/returns. The flag costs nothing extra: detection runs over the aspects the chart already computed.

Parameters

Parameter	Type	Required	Default	Description
`datetime`	string	One of `datetime` or `jd`	—	ISO 8601 UTC datetime
`jd`	number	One of `datetime` or `jd`	—	Julian Day in UT1
`bodies`	string	No	`"planets"`	Comma-separated body names
`sidereal`	string	No	—	Ayanamsha for sidereal mode
`aspects`	string	No	Major 7	Comma-separated aspect types to detect first
`orb`	number	No	—	Global orb override in degrees
`patterns`	string	No	All	Comma-separated pattern types to report (see below)
`stellium_min`	integer	No	`3`	Minimum members for a stellium (2–10)
`stellium_scope`	string	No	`"sign"`	`"sign"`, `"house"`, or `"conjunction"`
`lat`, `lon`	number	Only for `stellium_scope=house`	—	Observer location, used to compute house cusps
`system`	string	No	`"placidus"`	House system for `stellium_scope=house`

On the chart endpoints the boolean patterns=true turns detection on, and the type filter is called pattern_types instead.

Pattern types

Type	Definition	Focal body
`t_square`	An opposition plus two squares to an apex	The apex
`grand_trine`	Three mutual trines	—
`grand_cross`	Two oppositions with four squares	—
`yod`	A sextile plus two quincunxes to an apex	The apex
`kite`	A grand trine plus a fourth body opposing one vertex and sextile the other two	The fourth body
`mystic_rectangle`	Two oppositions whose four sides alternate trine and sextile	—
`stellium`	`stellium_min` or more bodies sharing a sign, a house, or a conjunction chain	—

Response

JSON

{
  "data": {
    "aspects": [
      { "body_a": "sun", "body_b": "moon", "aspect": "opposition", "angle": 179.95, "orb": 0.047, "max_orb": 8.0, "applying": null },
      { "body_a": "sun", "body_b": "jupiter", "aspect": "square", "angle": 91.44, "orb": 1.44, "max_orb": 7.0, "applying": null },
      { "body_a": "moon", "body_b": "jupiter", "aspect": "square", "angle": 88.60, "orb": 1.40, "max_orb": 7.0, "applying": null }
    ],
    "patterns": [
      {
        "pattern": "t_square",
        "bodies": ["sun", "moon", "jupiter"],
        "focal": "jupiter",
        "aspects": [
          { "body_a": "sun", "body_b": "moon", "aspect": "opposition", "angle": 179.95, "orb": 0.047, "max_orb": 8.0, "applying": null },
          { "body_a": "sun", "body_b": "jupiter", "aspect": "square", "angle": 91.44, "orb": 1.44, "max_orb": 7.0, "applying": null },
          { "body_a": "moon", "body_b": "jupiter", "aspect": "square", "angle": 88.60, "orb": 1.40, "max_orb": 7.0, "applying": null }
        ],
        "tightness": 1.44
      }
    ]
  },
  "meta": { "credits_used": 1, "...": "..." }
}

Field	Description
`pattern`	The pattern type
`bodies[]`	Members in chart order; the focal body is last where the pattern has one
`focal`	The apex (T-square, yod) or the tail (kite); absent otherwise
`aspects[]`	The forming aspects, verbatim from the request's aspect list
`tightness`	The widest forming orb in degrees; for a stellium, the members' longitude span

Rules worth knowing

Patterns are built from detected aspects, never re-derived from longitudes. A pattern cannot contain an aspect type your aspects parameter excluded — a yod needs quincunx, a mystic rectangle needs sextile. If you filter to a pattern whose forming aspects are missing from the aspect set, the response includes a warnings entry naming the missing type rather than silently returning nothing. The default major-7 set covers every pattern.
Containment is reported, not collapsed. A kite also reports its grand trine; a grand cross also reports its four T-squares. Filter on the client if you want only the largest figure.
Each body set is reported once per pattern type, in filter order and then body order.

Examples

The January 2024 full moon: a T-square with Jupiter at the apex

Bash

curl "https://api.morphemeris.com/v1/patterns?datetime=2024-01-25T18:00:00Z&patterns=t_square" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

javascript

const res = await fetch(
  "https://api.morphemeris.com/v1/patterns?datetime=2024-01-25T18:00:00Z&patterns=t_square",
  { headers: { Authorization: "Bearer morphemeris_live_YOUR_KEY" } },
);
const { data } = await res.json();
for (const p of data.patterns) {
  console.log(p.pattern, p.bodies.join("-"), "focal:", p.focal, "tightness:", p.tightness.toFixed(2));
}

Inside a natal chart

Bash

curl "https://api.morphemeris.com/v1/natal-chart?datetime=1990-06-15T18:30:00Z&lat=40.7128&lon=-74.006&patterns=true&stellium_scope=house" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

The chart's patterns array is populated; nothing else about the response changes, and the cost is still 2 credits.

Errors

Code	Cause
`invalid_parameter`	Unknown pattern type, `stellium_min` outside 2–10, or unknown `stellium_scope`
`missing_parameter`	`stellium_scope=house` without `lat` and `lon`

Aspect Patterns

On this page