GET /v1/returns — Find when a planet returns to its natal longitude and compute a full chart at that moment.

Planetary Returns

Compute a return chart for the exact moment a transiting body returns to its natal ecliptic longitude. Supports solar, lunar, and planetary returns for 18 bodies.

Text

GET  /v1/returns
POST /v1/returns

Credit cost: 2

Parameters

Parameter	Type	Required	Default	Description
`body`	string	Yes	—	Body to find the return for (see supported bodies)
`datetime`	string	One of `datetime` or `jd`	—	Natal birth datetime (ISO 8601 UTC)
`jd`	number	One of `datetime` or `jd`	—	Natal birth Julian Day in UT1
`search_start`	string	One of `search_start` or `search_start_jd`	—	When to start searching (ISO 8601 UTC)
`search_start_jd`	number	One of `search_start` or `search_start_jd`	—	Search start Julian Day in UT1
`lat`	number	Yes	—	Return chart location latitude
`lon`	number	Yes	—	Return chart location longitude
`count`	integer	No	`1`	Number of consecutive returns (max 13 for Moon, 5 for others)
`bodies`	string	No	`"planets"`	Comma-separated body names for the return chart
`system`	string	No	`"placidus"`	House system
`sidereal`	string	No	—	Ayanamsha for sidereal mode
`aspects`	string	No	Major 7	Comma-separated aspect types
`orb`	number	No	—	Global orb override in degrees

Supported bodies

sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, mean_node, true_node, chiron, pholus, ceres, pallas, juno, vesta

Unsupported bodies (e.g., lilith, numbered asteroids, fixed stars) return 400 body_not_eligible.

How it works

For someone born on June 15, 1990, requesting a solar return starting from January 1, 2024:

Compute natal longitude — Calculate the Sun's ecliptic longitude at the birth datetime (e.g., 84.37°)
Search for the return moment — Find the next time after search_start when the transiting Sun reaches 84.37°
Cast a full chart — Compute a natal-style chart (positions, houses, aspects, dignities) at the return moment and location

The location is typically the person's current residence, not their birth location — this is what makes each year's solar return chart unique even though the Sun returns to the same degree.

Response

JSON

{
  "data": {
    "return_body": "sun",
    "natal_longitude": 84.37,
    "charts": [
      {
        "metadata": {
          "source": "return",
          "jd": 2460458.234,
          "datetime": "2024-06-14T17:37:00Z",
          "lat": 38.4496,
          "lon": -78.8689,
          "..."
        },
        "bodies": [ "..." ],
        "houses": { "..." },
        "aspects": [ "..." ],
        "parallels": [],
        "dignities": [ "..." ]
      }
    ]
  },
  "meta": {
    "credits_used": 2,
    "..."
  }
}

When count > 1, the charts array contains multiple entries in chronological order.

Examples

Solar return for 2024

Bash

curl "https://api.morphemeris.com/v1/returns?\
body=sun&datetime=1990-06-15T18:30:00Z\
&search_start=2024-01-01T00:00:00Z\
&lat=38.4496&lon=-78.8689" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

javascript

const res = await fetch(
  "https://api.morphemeris.com/v1/returns?" + new URLSearchParams({
    body: "sun",
    datetime: "1990-06-15T18:30:00Z",
    search_start: "2024-01-01T00:00:00Z",
    lat: "38.4496", lon: "-78.8689",
  }),
  { headers: { Authorization: "Bearer morphemeris_live_YOUR_KEY" } }
);
const { data } = await res.json();

Python

import requests

res = requests.get(
    "https://api.morphemeris.com/v1/returns",
    params={
        "body": "sun",
        "datetime": "1990-06-15T18:30:00Z",
        "search_start": "2024-01-01T00:00:00Z",
        "lat": 38.4496, "lon": -78.8689,
    },
    headers={"Authorization": "Bearer morphemeris_live_YOUR_KEY"},
)
data = res.json()

Next 3 lunar returns

Bash

curl "https://api.morphemeris.com/v1/returns?\
body=moon&datetime=1990-06-15T18:30:00Z\
&search_start=2024-03-20T00:00:00Z\
&lat=38.4496&lon=-78.8689&count=3" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

javascript

const res = await fetch(
  "https://api.morphemeris.com/v1/returns?" + new URLSearchParams({
    body: "moon",
    datetime: "1990-06-15T18:30:00Z",
    search_start: "2024-03-20T00:00:00Z",
    lat: "38.4496", lon: "-78.8689",
    count: "3",
  }),
  { headers: { Authorization: "Bearer morphemeris_live_YOUR_KEY" } }
);
const { data } = await res.json();
// data.charts has 3 entries, one per lunar return

Python

import requests

res = requests.get(
    "https://api.morphemeris.com/v1/returns",
    params={
        "body": "moon",
        "datetime": "1990-06-15T18:30:00Z",
        "search_start": "2024-03-20T00:00:00Z",
        "lat": 38.4496, "lon": -78.8689,
        "count": 3,
    },
    headers={"Authorization": "Bearer morphemeris_live_YOUR_KEY"},
)
data = res.json()

Tips

Solar returns happen once per year, near the birthday. The exact time shifts by about 6 hours each year (and jumps back a day on leap years).
Lunar returns happen roughly every 27.3 days (the sidereal month). Use count to get several at once for monthly planning.
Saturn returns happen approximately every 29.5 years and are a staple of astrological practice. The first Saturn return (around age 29) is often considered a major life milestone.
For outer planets like Jupiter and Saturn, retrograde motion means the body may cross the natal longitude multiple times in a single cycle. The endpoint returns each crossing in chronological order.
The return chart location matters — use the person's current residence, not their birthplace, for the most relevant house placements.
To compare a return chart with the natal chart, use /v1/synastry with the natal datetime as one chart and the return moment as the other.

Planetary Returns

On this page