Chart Affinity API

Finding related factors inside one person’s chart — across natal, progressed, draconic and transit — rather than between two people. Every figure below is measured against the live CalculateHoroscopes API and the current engine.

How much comes back

live API · one person · 15 May 1980, London · 22 Sep 2026

Every transit row carries Begins and Ends. On the query date only 211 of 388 transits are active and 9 begin within 90 days — so the honest working set is about 570, not 740, and your “upcoming Venus opposition Uranus” is one of those 9.

Two findings that decide the design

37%   Venus Square Mars   <->   Venus Opposition Natal Uranus

Cost: pass the factors, store nothing

answering: all-to-the-matcher, or wide pools then filter

The full matrix of 740 factors is 273,430 pairs, which at full scoring is seconds — too slow. A two-stage pass fixes it, measured end to end on the real list:

Stage 1 keeps only pairs sharing two or more functions, and drops pairs that are the same body restated. It removes 99.6% of the work for nothing of value, because a pair sharing fewer than two functions cannot reach the cut anyway.

So: pass the user’s factor list and compute in memory. Precomputing wide pools per component would buy storage, staleness and a filtering step, to replace 68 ms of arithmetic. The only thing worth holding in memory is the engine itself.

What to actually return

three outputs · only the third is quadratic

1. Recurring archetypes — the headline

Straight from the real chart above, in 2ms:

Love x80    Expansion x79    Mind x70    Self x69    Will x69    Awakening x64

This is the “wider span” you were reaching for. It needs no threshold and no pairing.

2. Cross-layer echoes — the sharpest rows

The same normalised body pair appearing in two or more layers. Exact match, no scoring. A correction to your premise here: within one layer a body pair holds only one angle, so you are right that nobody has Moon square and opposition Pluto — but across layers the same pair recurs constantly, and that repetition is the strongest thing this feature can show.

3. Cross-route links — where affinity belongs

The two-stage pass. Be warned that 561 links from 740 factors is more than anyone can read, and the top of the list is thin:

100%  Transit Mercury in 1st House  <->  Mars Sextile Natal Mercury

Both contain Mercury, so they score perfectly while telling the reader little. Cap this output and rank it by something other than score — for example, prefer links that cross layers or routes over links inside one layer.

Live test — four real charts

4 people · 16 API calls · 403 query factors swept

Four birth charts pulled from the live API (Buenos Aires 1974, Tokyo 1991, Cairo 1966, Vancouver 2001), 718–750 factors each. A factor was picked from each chart and scored against the rest of that person’s own chart.

Every returned row was defensible. The engine found the same body pair in other layers, and found placements that carry the pattern through rulership without naming the planet:

Draconic Saturn Square Neptune   (Kenji, draconic)
   87%  Saturn Square Natal Neptune          transit    the same pair, now
   86%  Saturn in Aries in 12th House        draconic
   83%  Progressed Neptune in Capricorn      progressed  Capricorn IS Saturn
   78%  Neptune in Capricorn in 9th House    natal       so is this

What is still missed at 70, and whether it should be

The remaining near-misses are one class: the same body in a placement whose other end differs — Transit Chiron in 3rd House at 62% against a Chiron query, Transit Lilith in 3rd House at 62% against a Lilith one. They share the body but not the pattern. Whether “your Chiron is also busy over here” belongs in a related list is a product call, not a scoring one — and it is answered by output 1, the archetype tally, rather than by lowering the cut further.

One of the four returned a single row even at 70: a Lilith–Jupiter query, because Shadow is genuinely rare across that chart. That is honest scarcity and the UI needs to handle it.

The solution: ask it the other way round

theme → factors, not factor → factors

Everything above points one way. Asking “what relates to this factor?” is thin by nature — a chart rarely contains two factors with the same signature, so the pool is 1.9 at the calibrated cut and empty one time in eight. Asking “what recurs across this chart?” is always populated, because recurrence is what a chart is full of.

The unit is the one the matching engine already uses: an unordered pair of functions. Group the person’s own factors by it, keep the themes appearing in three or more layers, rank by layer span then by count. Measured on the four live charts:

The same content the factor-first query returned, but grouped and readable — here is Kenji’s, the theme his random factor belonged to:

Dissolution x Structure     7 factors across 4 layers
   birthchart   Neptune in Capricorn in 9th House
   transit      Transit Saturn in 12th House  ·  Neptune Sextile Natal Saturn  (+1)
   progressed   Progressed Neptune in Capricorn
   draconic     Saturn in Aries in 12th House  ·  Draconic Saturn Square Neptune

And it rescues the empty case. Nadia’s factor-first query returned nothing at all; theme-first she has 62 themes across three or more layers, led by Love × Will with 11 factors. A person is never told “nothing relates to this”.

So: theme-first is the feature; factor-first affinity is the drill-down. Tap a theme to see the factors carrying it; tap a factor to ask what else in the chart resembles it, at cut: 70. The first view is a linear group-by over the user’s own list — 2 ms, no matcher call at all. The matcher is only needed for the drill-down, and that is where the 68 ms two-stage pass earns its place.

API shape

POST /affinity/chart
{
  "factors": [
    {"name": "Venus Square Mars",             "category": "Planet Aspects"},
    {"name": "Sun in Taurus in 9th House",    "category": "Planets in Houses"},
    {"name": "Venus Opposition Natal Uranus", "category": "Transit Aspects",
     "begins": "2026-10-04", "ends": "2026-10-19"}
  ],
  "activeOn": "2026-09-22",
  "include": ["archetypes", "echoes", "links"],
  "cut": 85, "maxLinks": 40
}

{
  "archetypes": [{"function":"Love","count":80,"factors":[...]}],
  "echoes":     [{"pair":"Mars–Venus","layers":["natal","draconic"],"factors":[...]}],
  "links":      [{"a":"...","b":"...","score":93,"crossesLayer":true}],
  "unresolved": []
}

• Send category. The same name lives in several layers; without it the engine takes the first match and may read a synastry contact as natal.
• Pass the transit windows through. The API already returns them, and activeOn is what separates 211 live transits from 388 rows of mostly-not-now.
• Canonicalise names server-side and report what failed. In testing, Pluto Square Mars and Moon Trine Sun resolved to nothing because the corpus stores those pairs in the other order — they did not error, they silently vanished. On a feature whose whole job is seeing the entire chart, silent loss is the worst failure mode.

Open, and I would not guess

The tally has no baseline. “Love × 80” may just mean this chart is large, or that Love is common in everyone’s. It wants normalising against the average chart, which nobody has measured. Ship it raw, look at real output across a few hundred charts, then decide.

Output 3 needs a product decision, not a threshold. 561 links is noise; the fix is what you rank by, and that depends on what the feature is for.