Planetary returns

A planetary return occurs when a transiting planet returns to its exact natal position. Every planet has a return cycle that marks the beginning of a new phase for its themes.

GET/api/returnsPro

Calculate when a planet returns to its natal position for a given year. Returns the exact date, time, and planetary position of the return.

Advanced Chart API only

This endpoint requires the Advanced Chart API product. It is not available on the Basic Chart API tier.

Supported planets

Planet	Typical return cycle	Key themes
`sun`	~1 year	Identity, vitality, life direction
`moon`	~27.3 days	Emotions, instincts, inner security
`mercury`	~1 year	Communication, thinking, learning
`venus`	~1 year	Love, values, aesthetics
`mars`	~2 years	Drive, action, assertion
`jupiter`	~12 years	Growth, luck, expansion
`saturn`	~29.5 years	Structure, maturity, responsibility
`chiron`	~50 years	Healing, wounds, wisdom
`uranus`	~84 years	Revolution, awakening, freedom
`neptune`	~165 years	Spirituality, dreams, dissolution
`pluto`	~248 years	Transformation, power, rebirth
`north-node`	~18.6 years	Life direction, karmic path, purpose

Outer planet returns

Uranus, Neptune, and Pluto returns take longer than a typical human lifetime. These are useful for historical research, generational analysis, or the rare Uranus return (~84 years).

Request

Parameters

birthDate reqstringDate of birth in YYYY-MM-DD format

birthTime reqstringTime of birth in HH:MM (24-hour) format

birthLocation reqstringCity and region (e.g. "New York, NY"). Used for timezone and coordinate lookup.

planet reqstringPlanet to calculate return for. One of: sun, moon, mercury, venus, mars, jupiter, saturn, chiron, uranus, neptune, pluto, north-node

year reqnumberThe year to find the return in (e.g. 2026). For Moon returns, returns the first occurrence in this year.

latitude numberOverride latitude. Skips geocoding when provided with longitude.

longitude numberOverride longitude. Skips geocoding when provided with latitude.

thd-api

Response

✓ doneapplication/json

{
"success": true,
"meta": {
  "version": "1.0.0",
  "timestamp": "2026-03-20T12:00:00.000Z",
  "endpoint": "returns"
},
"data": {
  "birthInfo": {
    "date": "1990-05-15",
    "time": "14:30",
    "location": "New York, NY",
    "timezone": "America/New_York",
    "utcOffset": -4
  },
  "planet": "Sun",
  "year": 2026,
  "returnNumber": 36,
  "natalPosition": {
    "longitude": 54.32,
    "sign": "Taurus",
    "positionInSign": "24°19'",
    "gate": 2,
    "line": 3
  },
  "return": {
    "exactDatetime": "2026-05-15T18:42:31.000Z",
    "localDatetime": "2026-05-15T14:42:31-04:00",
    "longitude": 54.32,
    "sign": "Taurus",
    "positionInSign": "24°19'",
    "gate": 2,
    "line": 3,
    "isRetrograde": false
  },
  "returnChart": {
    "ascendant": { "longitude": 195.7, "sign": "Libra" },
    "moonSign": "Cancer",
    "moonLongitude": 102.45
  },
  "cycle": {
    "previousReturn": "2025-05-15T11:18:05.000Z",
    "nextReturn": "2027-05-15T00:27:14.000Z",
    "cycleLengthDays": 365.26
  }
}
}

Response fields

Field	Description
`planet`	The planet for which the return was calculated
`year`	The requested year
`returnNumber`	Which return this is in the person's life (e.g. 36th Solar Return = 36th birthday)
`natalPosition`	The planet's position at birth — longitude, zodiac sign, and Human Design gate/line
`return.exactDatetime`	The precise UTC moment the transiting planet reaches the natal longitude
`return.localDatetime`	The return moment in the birth location's timezone
`return.gate` / `return.line`	The Human Design gate and line at the moment of return (same as natal)
`return.isRetrograde`	Whether the planet is retrograde at the moment of return
`returnChart`	Key chart points at the moment of return — ascendant and moon position
`cycle`	Previous and next return dates, plus the cycle length in days

Moon returns

The Moon returns approximately every 27.3 days. When requesting a Moon return, the API returns the first lunar return of the specified year. Use the cycle.nextReturn field to step through subsequent returns.