Astrocartography

A natal chart is cast for one place. Move the birth to a different longitude and latitude, keep the moment, and the planets stay where they are in the zodiac while the angles — Ascendant, Midheaven, and their opposites — swing around to meet them. Astrocartography (Jim Lewis's term; "relocation mapping" is the older one) draws, for each planet, the curve on Earth's surface along which that planet would be exactly on an angle. Four curves per body: MC, IC, Ascendant, Descendant.

/v1/astrocartography returns those curves as line geometry, and extends the idea to any house cusp in any house system.

The geometry, briefly

Fix the moment. Every place on Earth then has a local sidereal time (ARMC = GAST + longitude), and every house cusp is a function of that and the latitude.

• Midheaven and IC lines are meridians. A body culminates wherever the local sidereal time equals its right ascension, which is a fixed longitude — a straight north–south line. The IC line is 180° away.
• Ascendant and Descendant lines curve. A body is rising where its hour angle satisfies cos H = −tan φ · tan δ; solving that for each latitude gives an S-shaped curve. Beyond the latitude where |tan φ · tan δ| > 1 the body is circumpolar — it never rises or sets — and the line ends. That is the circumpolar termination.
• Cusp lines are found numerically. Along one parallel of latitude the body is on cusp k where the house position minus k is zero; the API brackets every sign change with a scan in ARMC and refines each by bisection. In a quadrant system the cusp-1 and cusp-10 lines coincide with the Ascendant and Midheaven lines — which is the check the implementation is tested against.

Zodiacal vs. mundane

Published astrocartography maps flatten each body onto the ecliptic — they use its zodiacal longitude and ignore its ecliptic latitude — so that the lines agree with what a relocated chart shows. That is the zodiacal mode and the default.

mundane mode uses the body's true position in the sky. The Moon can be 5° off the ecliptic, Pluto 17°, and for them the two answers diverge visibly: the mundane Ascendant line is where the Moon is actually on the horizon, the zodiacal one is where a chart would put it on the Ascendant. Neither is wrong; they answer different questions.

Why segments have an end

A line is not always one curve. It may cross the ±180° meridian, it may leave the region where a house system is defined (Placidus and Koch have no cusps inside the polar circles), it may simply stop because the body is circumpolar, or the sampling may run out at max_latitude. The API splits lines at every such event and labels each piece with why it stopped, so a renderer can tell "this line ends here" from "this line continues off the map" — and never has to guess whether two adjacent points should be joined.

What it is not

The API computes lines, not meaning. It does not score locations, rank cities, or combine lines into "power zones"; those are interpretive layers a client builds on top. Parans — the latitudes where two bodies are simultaneously angular — fall out as intersections of the lines and are left to the renderer.