/v1/transit/windows

Every stay of one planet in a sidereal sign over a date range, with exact ingress times and retrograde re-entries; with birth details also the house from the natal Moon and lagna.

What this tells you

Every sign-to-sign stay of one planet over a range of years, with exact ingress times and retrograde re-entries marked. With birth details each window also says which house it is from the natal Moon and lagna, so you can build "Jupiter in your 7th from 2027-06 to 2028-06" timelines without your own ephemeris. Rahu and Ketu use the mean node, like /v1/chart/planets. Every instant is given as *_local (RFC 3339 with offset, in `tz`) and *_jd (Julian Day, UT). Ingress times are bisected to about 1 second, with the ayanamsa of each moment.

The planet is `planet`; the optional natal chart is under `birth.*`; `from` and `tz` are unprefixed.

Request

All requests require an Authorization header with your dv_live_* API key.

example request

curl "https://api.lifeastroapi.com/v1/transit/windows?planet=saturn&birth.date=1990-01-15&birth.time=10%3A30&birth.tz=Asia%2FKolkata&birth.lat=19.076&birth.lon=72.8777&from=2027-01-15" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query parameters

Checked against the API: a parameter is marked required when the request fails without it.

Name	Required	Example	Description
`planet`	yes	`saturn`	Planet id.
`birth.date`	no	`1990-01-15`	Birth date (YYYY-MM-DD).
`birth.time`	no	`10:30`	Birth time (HH:MM, 24-hour, local). Defaults to 12:00.
`birth.tz`	yes	`Asia/Kolkata`	Birth place timezone: IANA name (Asia/Kolkata) or UTC offset (+05:30).
`birth.lat`	no	`19.076`	Birth place latitude in decimal degrees.
`birth.lon`	no	`72.8777`	Birth place longitude in decimal degrees.
`from`	no	`2027-01-15`	Start date YYYY-MM-DD (local midnight in tz). Defaults to now.
`years`	no	—	Span in calendar years after from (per-planet default and max, see description).
`ayanamsa`	no	—	Ayanamsa (sidereal offset) to use. Defaults to lahiri.

Response (200 OK)

The real response to the example request above, generated from the API itself. Long arrays are trimmed to their first two items. Field names are stable across versions.

200 response

{
  "planet": "saturn",
  "ayanamsa": "lahiri",
  "tz": "Asia/Kolkata",
  "from_local": "2027-01-15T00:00:00+05:30",
  "from_jd": 2461420.270833,
  "to_local": "2052-01-15T00:00:00+05:30",
  "to_jd": 2470551.270833,
  "natal_moon_sign_index": 4,
  "natal_lagna_sign_index": 10,
  "windows": [
    {
      "sign_index": 11,
      "start_local": "2025-03-29T21:43:25+05:30",
      "end_local": "2027-06-03T04:43:30+05:30",
      "start_jd": 2460764.175982,
      "end_jd": 2461559.467711,
      "retro_reentry": false,
      "retrograde_at_start": false,
      "house_from_moon": 8,
      "house_from_lagna": 2
    },
    {
      "sign_index": 0,
      "start_local": "2027-06-03T04:43:30+05:30",
      "end_local": "2027-10-20T08:13:25+05:30",
      "start_jd": 2461559.467711,
      "end_jd": 2461698.613482,
      "retro_reentry": false,
      "retrograde_at_start": false,
      "house_from_moon": 9,
      "house_from_lagna": 3
    }
  ]
}

Field reference

Every field in the response, with its type, a real example, and what it means.

Field	Type	Meaning
planet	string	Planet id you asked for (`planet`, required). example: `"saturn"`
ayanamsa, tz	string	Ayanamsa and the zone of every *_local value (`tz`, default birth.tz, else UTC). example: `"lahiri", "Asia/Kolkata"`
from_local, to_local (+ _jd)	string, number	Range start (`from`, local midnight, default now) and from + `years`. example: `"2027-01-15T00:00:00+05:30", "2052-01-15T00:00:00+05:30"`
natal_moon_sign_index, natal_lagna_sign_index	integer (0–11)	Natal Moon sign (with birth.date/time/tz) and natal lagna sign (also needs birth.lat/lon). Absent without birth details. example: `4, 10`
windows[]	array	Every stay of the planet in one sidereal sign that overlaps the range, with its true start and end. example: `[{ "sign_index": 11, "start_local": "2025-03-29T21:43:25+05:30", "end_local": "2027-06-03T04:43:30+05:30", … }]`
windows[].retro_reentry	boolean	True for a stay in a sign the planet had left on its retrograde loop (A→B→A or B→A→B). example: `false`
windows[].retrograde_at_start	boolean	Motion at the entering ingress (same flag as /v1/planet-moments/ingress is_retrograde_at_ingress). example: `false`
windows[].house_from_moon, house_from_lagna	integer (1–12)	Whole-sign house of that sign counted from the natal Moon and from the natal lagna, when birth details are given. example: `8, 2`

Usage tips

How to use it

Years per planet
years has a per-planet default and maximum: 25 / 60 for jupiter, saturn, rahu, ketu; 5 / 20 for sun, mercury, venus, mars; 1 / 2 for moon.
Gochar timelines
Combine the windows of jupiter, saturn, rahu and ketu (house_from_moon) for a classical gochar overview; one call per planet.

Errors

Every error follows the same envelope. Use the error.code field (not the message) for conditional logic in your integration.

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

402 Payment Required

{
  "error": {
    "code": "trial_exhausted",
    "message": "your free trial credits are exhausted — pick a plan to continue",
    "top_up_url": "https://lifeastroapi.com/pricing",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded; retry after 12 seconds",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

Try it

Get a dv_live_* key from your dashboard and paste into the cURL snippet above. New accounts get 7,500 welcome credits plus 1,500 free credits a month. Sign up.