Track Planetary Transits
Monitor planetary positions over time to detect sign changes, retrogrades, and aspects.
Track Planetary Transits
Transits are the current (or future) positions of planets relative to a natal chart or fixed zodiacal points. Use the /v1/positions endpoint to fetch positions at any moment in time.
Daily transit snapshot
curl "https://api.morphemeris.com/v1/positions?\
datetime=2024-06-20T12:00:00Z\
&bodies=sun,moon,mercury,venus,mars,jupiter,saturn" \
-H "Authorization: Bearer morphemeris_live_YOUR_KEY"Tracking movement over time
To watch a planet's movement (e.g., for retrograde detection or sign ingress), fetch positions at regular intervals:
const dates = [];
const start = new Date("2024-06-01T00:00:00Z");
for (let i = 0; i < 30; i++) {
const d = new Date(start);
d.setDate(d.getDate() + i);
dates.push(d.toISOString());
}
const positions = await Promise.all(
dates.map(async (dt) => {
const res = await fetch(
`https://api.morphemeris.com/v1/positions?datetime=${dt}&bodies=mercury`,
{ headers: { Authorization: `Bearer ${apiKey}` } }
);
const { data } = await res.json();
return { date: dt, ...data[0] };
})
);
// Detect retrograde periods
for (const pos of positions) {
if (pos.retrograde) {
console.log(`Mercury retrograde on ${pos.date}: ${pos.sign} ${pos.sign_degree.toFixed(2)}°`);
}
}
// Detect sign changes
for (let i = 1; i < positions.length; i++) {
if (positions[i].sign !== positions[i - 1].sign) {
console.log(`Mercury entered ${positions[i].sign} on ${positions[i].date}`);
}
}Computing aspects to natal positions
To find transits aspecting natal planets, compare the current longitude to the natal longitude:
function getAspect(transitLon, natalLon, orb = 1.0) {
const aspects = [
{ name: "conjunction", angle: 0 },
{ name: "sextile", angle: 60 },
{ name: "square", angle: 90 },
{ name: "trine", angle: 120 },
{ name: "opposition", angle: 180 },
];
const diff = Math.abs(transitLon - natalLon) % 360;
const normalized = diff > 180 ? 360 - diff : diff;
for (const aspect of aspects) {
if (Math.abs(normalized - aspect.angle) <= orb) {
return aspect.name;
}
}
return null;
}Tips
- Each position request costs 1 credit. A month of daily transits for 7 planets = 30 credits.
- Use the
speedfield to detect stations (when speed approaches 0) — these indicate retrograde turning points. - The
retrogradeboolean is derived from the speed: negative speed = retrograde.