Transit overlay

A pair of endpoints that compute a chart for a future moment and compare it against the natal. The math reuses the natal's birth coordinates and ayanamsha, so the transit chart is a true overlay, not a separately-rooted chart.

Both endpoints accept a single query parameter:

Param	Type	Notes
at	ISO-8601 datetime	The moment to compute the transit for. Must be timezone-aware.

GET /v1/vedic/charts/{id}/transits/contacts

Finds every (transit → natal) aspect or sign-conjunction. Returns edges with strength so callers can rank by significance.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.astrolinkers.com/v1/vedic/charts/$CHART/transits/contacts?at=2026-11-01T12:00:00Z"

{
  "natal_chart_id": "01HKD…",
  "moment": "2026-11-01T12:00:00+00:00",
  "contacts": [
    {"transit_planet": "jupiter", "natal_planet": "sun",
     "kind": "conjunction", "strength": 60.0},
    {"transit_planet": "saturn", "natal_planet": "moon",
     "kind": "aspect", "strength": 60.0},
    {"transit_planet": "mars", "natal_planet": "venus",
     "kind": "aspect", "strength": 45.0}
  ]
}

• conjunction — both planets sit in the same sign at the moment in question (full 60 Virupa).
• aspect — drishti from the transiting planet using the same Parashara + special-aspect rules as /v1/vedic/charts/{id}/aspects.

GET /v1/vedic/charts/{id}/transits/navamsa-activations

A finer-grained timing signal: for each natal planet, lists the transiting planets currently sharing its D9 (navamsa) sign. The navamsa is the second-most-important varga in classical Vedic, and transit + natal sharing it is often the moment when a yoga "lights up".

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.astrolinkers.com/v1/vedic/charts/$CHART/transits/navamsa-activations?at=2026-11-01T12:00:00Z"

{
  "natal_chart_id": "01HKD…",
  "moment": "2026-11-01T12:00:00+00:00",
  "activations": [
    {"transit_planet": "jupiter", "natal_planet": "sun",
     "navamsa_sign": "aries"},
    {"transit_planet": "saturn", "natal_planet": "moon",
     "navamsa_sign": "capricorn"}
  ]
}

GET /v1/vedic/charts/{id}/transits?at=<iso>

The full transit snapshot at a moment: every transiting planet (with its natal house), plus the contacts and navamsa_activations from the two endpoints above, in one call.

{
  "chart_id": "01HKD…",
  "method_version": "v2",
  "at": "2026-11-01T12:00:00Z",
  "planets": [
    { "planet": "jupiter", "longitude": 72.4, "sign": "gemini",
      "speed_per_day": 0.21, "is_retrograde": false, "natal_house": 11 }
  ],
  "contacts": [ { "transit_planet": "jupiter", "natal_planet": "sun", "kind": "conjunction", "strength": 60.0 } ],
  "navamsa_activations": [ { "transit_planet": "saturn", "natal_planet": "moon", "navamsa_sign": "capricorn" } ],
  "features_used": [ { "source": "transits", "version": "v2", "fields": ["contacts"] } ]
}

GET /v1/vedic/charts/{id}/transit-events?starts_at=<iso>&ends_at=<iso>

Scans a date window for discrete transit events — sign ingresses, retrograde shifts, and nakshatra/pada changes. Optional precision (default daily) sets the scan granularity.

{
  "chart_id": "01HKD…",
  "method_version": "v2",
  "starts_at": "2026-01-01T00:00:00Z", "ends_at": "2027-01-01T00:00:00Z",
  "precision": "daily",
  "events": [
    {
      "planet": "saturn", "event_type": "sign_ingress", "moment": "2026-03-29T…",
      "longitude": 330.0, "from_sign": "aquarius", "to_sign": "pisces",
      "from_nakshatra": "shatabhisha", "to_nakshatra": "purva_bhadrapada",
      "from_pada": 4, "to_pada": 1
    }
  ],
  "features_used": []
}

event_type is one of sign_ingress / retrograde / nakshatra_change (the from_* / to_* fields are populated for whichever boundary the event crosses).

GET /v1/vedic/charts/{id}/sade-sati?at=<iso>

Saturn's 7½-year transit over the natal Moon — the classic Sade Sati read at a moment.

{
  "chart_id": "01HKD…", "method_version": "v2", "at": "2026-06-05T00:00:00Z",
  "is_active": true, "phase": "peak",
  "natal_moon_sign": "aquarius", "saturn_sign": "aquarius",
  "house_from_moon": 1, "is_ashtama_shani": false,
  "features_used": []
}

Field	Type	Notes
is_active	bool	Whether Sade Sati is running at at.
phase	string	rising / peak / setting (the three sign-positions), or none.
natal_moon_sign / saturn_sign	string	The two signs being compared.
house_from_moon	int	Saturn's house counted from the natal Moon (12 / 1 / 2 during Sade Sati).
is_ashtama_shani	bool	Saturn transiting the 8th from the Moon (a separate affliction).

GET /v1/vedic/charts/{id}/next-important-transit?starts_at=<iso>&ends_at=<iso>

The single highest-priority transit in a window — picks the most significant of the Sade Sati status, the upcoming events, and the strongest contact.

{
  "chart_id": "01HKD…", "method_version": "v2",
  "starts_at": "2026-06-05T00:00:00Z", "ends_at": "2027-06-05T00:00:00Z",
  "priority": 90, "title": "Saturn enters Pisces", "kind": "sign_ingress",
  "event": { "…": "a transit-event object, or null" },
  "contact": { "…": "a contact object, or null" },
  "sade_sati": { "…": "the sade-sati object" },
  "features_used": []
}

GET /v1/vedic/charts/{id}/daily-weather?day=<YYYY-MM-DD>

Personal "weather" cards for a single calendar day — the day's significant transit influences, scored and ready to render. day is an ISO date (no time).

{
  "chart_id": "01HKD…", "method_version": "v2", "day": "2026-06-05",
  "cards": [
    { "kind": "transit_contact", "title": "Jupiter trine Moon", "priority": 70,
      "signals": ["benefic_contact", "navamsa_activation"] }
  ],
  "features_used": []
}

Composing with the predictive engine

Both contact endpoints are consumed by the future date-aware variant of Materialization probability — the natal-only base_potential × a contact-modulated factor will produce a true 0..1 probability for a specific date.