Transit Alerts: Tell Each User When a Planet Changes Sign

A transit alert needs three things. You need the date a planet changes sign, the user's Moon sign, and one line of math. The sky does not care who your user is, so the dates come from one call for everyone. The personal part is a count.

Get the dates. Call GET /v1/sky/events with a date range and the user's time zone. It returns each ingress (a planet entering a new sign) and each retrograde start, when a planet seems to move backward.

Make it personal. Gochar is the Vedic word for transits. It counts from the user's Moon sign, the sign the Moon was in at birth. Call that sign house 1 and count forward to the planet's new sign. Rahu entering Capricorn is the 9th house for a Taurus Moon and the 1st for a Capricorn Moon.

Pick how often to send. We measured 10 years of sky events. Alerting on every sign change sends 50 messages a year to each user, about one a week. Alerting only on Jupiter, Saturn, and Rahu with Ketu sends 3.8 a year. Add their retrograde starts and it is 5.7.

The rest of this post shows the routes, a real 4-month list, the counting code, and how to word the messages.

What a useful transit alert says

A useful alert names one event, says where it lands for this user, and stops there. "Saturn enters your 4th house from the Moon" is personal and true. It is also short enough for a lock screen.

Two kinds of events are worth an alert. The first is a planet entering a new sign. The second is a slow planet turning retrograde. Retrograde is the stretch when a planet seems to move backward against the stars, as seen from Earth. Our retrograde glossary entry explains why it happens.

Gochar counts from the Moon sign because the classical lists of good and hard transit results start there. Our gochar glossary entry covers the full method. Many astrologers also count from the ascendant (the rising sign). The chart-based transit routes return both, but their traditional results use the Moon.

A sign change is the right trigger because it is a clean moment. Before it, the planet sits in one house for this user. After it, the planet sits in the next one. Nothing in between needs a message.

The routes that give the dates

Four public routes do the work for transit alerts. Each one fits a different job.

For alerts, GET /v1/sky/events does the heavy lifting. It needs no birth data, so one call serves every user in a time zone. The kind filter takes ingress and retrograde, and leaves out the other event kinds.

POST /v1/transits/forecast is the shortcut when you want the house without counting. Send a user's birth details and a date range. Each period comes back with house_from_moon already filled in.

The next four months, from a real run

We called GET /v1/sky/events on our local API for Nov 14, 2026 to Mar 14, 2027, in New York time. Then we called POST /v1/transits/forecast for John Doe (Aug 15, 1990, 10:30 AM, New York), whose Moon sign is Taurus.

That is 18 sign changes and 3 retrograde starts in 4 months. Rahu and Ketu always move at the same moment, so an app that joins them sends 20 messages. That is one message every 6 days, before any user choice.

The dates of the slow planets after March are in our post on Jupiter, Saturn, Rahu and Ketu transits. Mercury's full retrograde calendar is in Mercury retrograde dates.

One sky event, 12 messages

The count is the same for every app and every language. Put the 12 signs in order, from Aries to Pisces. Find how many steps it takes to go forward from the Moon sign to the planet's sign, then add 1.

Here is Rahu entering Capricorn on Nov 25, 2026, counted for each Moon sign.

So one API call gives 12 different messages. Every user with the same Moon sign gets the same house, so you only need 12 versions of each alert.

This Node.js code asks for the week ahead and writes John's messages. Run it on your server, so your API key stays private.

// Transit alerts for the week ahead (Node 18 or later).
const BASE_URL = "https://apiforastrology.com/api/astrology/v1";

const SIGNS = [
  "Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo",
  "Libra", "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces",
];

// 1. Ask for the sign changes and retrograde starts in the next 7 days.
async function getWeekAhead(from, to, timezone) {
  const query = new URLSearchParams({ from, to, timezone, kind: "ingress,retrograde" });
  const response = await fetch(`${BASE_URL}/sky/events?${query}`, {
    headers: { Authorization: `Bearer ${process.env.ASTROLOGY_API_KEY}` },
  });
  const answer = await response.json();
  // The answer also lists stays that began before "from". Keep only new events.
  return answer.events.filter((event) => !event.started_before_the_window);
}

// 2. Count the Moon sign as house 1, then count forward to the planet's sign.
function houseFromMoon(moonSign, planetSign) {
  const steps = (SIGNS.indexOf(planetSign) - SIGNS.indexOf(moonSign) + 12) % 12;
  return steps + 1;
}

function ordinal(number) {
  if (number === 1) return "1st";
  if (number === 2) return "2nd";
  if (number === 3) return "3rd";
  return `${number}th`;
}

// 3. Write one short message for one user.
function alertText(event, moonSign) {
  if (event.kind === "retrograde") {
    return `${event.graha} turns retrograde today. It will seem to move backward for a while.`;
  }
  const house = houseFromMoon(moonSign, event.sign);
  return `${event.graha} enters ${event.sign} today, your ${ordinal(house)} house from the Moon.`;
}

// John Doe's Moon sign is Taurus. His time zone is New York.
const events = await getWeekAhead("2026-11-21", "2026-11-28", "America/New_York");
for (const event of events) {
  console.log(event.starts, alertText(event, "Taurus"));
}

We ran it against our local API. It printed three lines. John Doe, Moon sign Taurus, New York:

2026-11-22 Venus enters Libra today, your 6th house from the Moon.
2026-11-25 Ketu enters Cancer today, your 3rd house from the Moon.
2026-11-25 Rahu enters Capricorn today, your 9th house from the Moon.

Two details in that code matter. The route refuses a range where to equals from, so ask for a week, not a day. And the answer also lists stays that began earlier, such as Saturn's stay in Pisces. In our week-ahead run, 12 events came back and only 3 were new. The started_before_the_window flag tells them apart.

Checking the count against the API

Simple math is only useful if it matches the engine. So we checked it. For each of the 18 sign changes in our 4-month run, we counted John's house by hand from Taurus. Then we compared it with house_from_moon from POST /v1/transits/forecast.

All 18 matched. The count is plain whole-sign counting: the sign is the house, with no degrees involved. That is why one line of code can do it.

The forecast route also gives you a traditional result for each period, and a strength label. Those are for a detail screen, not a push message. A one-line alert has no room for the reasons behind a label. You can see the full per-user response on the transits and forecasts feature page.

How often each planet would send an alert

We called GET /v1/sky/events for 10 years, 2027 to 2036, two years per call, in New York time. Then we counted the events that started inside each window.

The Moon is left out of sky events, because it is too fast. We counted it with POST /v1/transits/ingresses/Moon, one month per call. It changed sign 160 times in 2027.

Here is what those counts mean for one user, per year.

The sign changes are spread through the year. Across all 120 months, every month had at least 1. The busiest month, October 2029, had 7. The average was 4.17 a month.

Retrograde returns, time zones and other edge cases

A planet can enter the same sign twice. When a planet turns retrograde close to a sign line, it can drop back across that line into the previous sign. Saturn enters Aries on Jun 2, 2027, moves back into Pisces on Oct 19, 2027, and enters Aries again on Feb 23, 2028. POST /v1/transits/ingresses/{graha} marks each return with resumes_visit: true. Over our 10 years, this happened 14 times for Mercury, 6 for Jupiter, 3 for Venus, 2 for Saturn and 1 for Mars.

Word these returns differently. "Saturn moves back into Pisces for a while" tells the user what happened. A plain second "Saturn enters Pisces" can read like a repeat.

Rahu and Ketu move together. They are not bodies but the Moon's nodes, where its orbit cuts the Sun's yearly track. They always sit opposite each other, and they move backward through the signs as their normal motion. So their sign change is one moment with two houses: the 9th and the 3rd for John. Send one message that names both.

The date depends on the time zone. We ran the same 4 months in India time. 10 of the 21 events started one day later in India than in New York. Jupiter turns retrograde on Dec 12, 2026, in New York and on Dec 13 in India. So call the route with each user's own time zone, and the "today" in your message stays true.

Short ranges cut stays off. In a one-week answer, a stay that runs past the range shows runs_past_the_window: true. Its ends value is then only where the calculation stopped. That is why our retrograde message does not print an end date.

Before you build the alert job, try the free kundli tool on your own birth details. It shows the Moon sign that every count in this post starts from.

Writing alerts people keep turned on

Users can turn alerts off in their phone settings. These habits use the counts above to keep each message worth opening.

Start with the slow planets. Jupiter, Saturn, Rahu and Ketu give 3.8 sign changes a year. Let users turn on Mars, the Sun, Mercury and Venus if they want more. Never push the Moon: 160 sign changes a year is a message every two or three days.

Send one message per moment. Join Rahu and Ketu. If two planets change sign on the same day, put both in one message.

Use calm, plain words. Say what moved and where it lands. Leave out words like "bad" or "unfavorable", even when the traditional table says so. One moving planet says less than the whole birth chart. Link the message to a screen where the user can read more, at their own pace.

Send at a sensible local hour. The event date is in the user's time zone, so the message can go out in their morning, not at midnight.

Explain the house once. The first alert can say "Houses here are counted from your Moon sign". After that, users know the pattern.

Sade sati, Saturn's 7.5-year pass around the Moon sign, has three phases and breaks. That is more than a one-line alert can carry. Our post on how sade sati is calculated shows its dates and breaks. The field list for every transit route is in the transits API reference.

The short version

Get the dates from one call, count the house from each user's Moon sign, and choose the planets on purpose. The math takes one line. The choice of planets decides whether a user hears from you 4 times a year or 50.