Western Planetary Return

Next return chart for any planet after a given date. Finds the exact moment the specified planet returns to its natal tropical longitude and builds a complete Western natal chart for that moment at the birth location. Supported planets: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto.

Endpoint

POST /v1/western/planetary-return

Request parameters

Field	Type	Required	Description
location	string \| null	No	City name to resolve to lat/lon/tz automatically. Example: 'Mumbai' or 'New Delhi, India'. If provided, latitude, longitude and timezone are not required.
name	string	No	Person name associated with the birth record
date	string	Yes	Birth date in YYYY-MM-DD format
time	string \| null	No	Birth time in HH:MM 24-hour format. If omitted, sunrise chart is used as fallback.
latitude	number \| null	No	Latitude. Required if location not provided.
longitude	number \| null	No	Longitude. Required if location not provided.
timezone	string \| null	No	IANA timezone. Required if location not provided.
ayanamsa	string	No	Sidereal ayanamsa mode used in calculations
planet	string	Yes	Planet name for the return chart
after_date	string \| null	No	Find the next return after this date (YYYY-MM-DD). Defaults to today.

Example request

curl
Python
TypeScript

curl -X POST "https://api.asterwise.com/v1/western/planetary-return" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Arjun Mehta","date":"1985-11-12","time":"06:45","latitude":19.076,"longitude":72.8777,"timezone":"Asia/Kolkata","planet":"Jupiter","after_date":"2026-01-01"}'

import asterwise
from asterwise.api.western_astrology_api import WesternAstrologyApi
from asterwise.models.planetary_return_request import PlanetaryReturnRequest

configuration = asterwise.Configuration(
    host="https://api.asterwise.com",
    access_token="YOUR_API_KEY",
)

request = PlanetaryReturnRequest(
    name="Arjun Mehta",
    date="1985-11-12",
    time="06:45",
    latitude=19.076,
    longitude=72.8777,
    timezone="Asia/Kolkata",
    planet="Jupiter",
    after_date="2026-01-01",
)

with asterwise.ApiClient(configuration) as client:
    api = WesternAstrologyApi(client)
    result = api.western_planetary_return(planetary_return_request=request)
    print(result)

import { createClient, createConfig, westernPlanetaryReturn } from 'asterwise';

const client = createClient(createConfig({
  baseUrl: 'https://api.asterwise.com',
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
}));

const result = await westernPlanetaryReturn({
  client,
  body: {
      "name": "Arjun Mehta",
      "date": "1985-11-12",
      "time": "06:45",
      "latitude": 19.076,
      "longitude": 72.8777,
      "timezone": "Asia/Kolkata",
      "planet": "Jupiter",
      "after_date": "2026-01-01"
  },
});

console.log(result.data);

Example response

{
  "success": true,
  "message": "success",
  "data": {
    "planet": "Jupiter",
    "natal_longitude": 309.615962,
    "return_utc": "2033-01-13T20:39:32Z",
    "return_jd": 2463611.360779,
    "chart": {
      "zodiac": "tropical",
      "house_system": "placidus",
      "ascendant": {
        "longitude": 223.233989,
        "sign": "Scorpio",
        "sign_index": 7,
        "degree_in_sign": 13.233989
      },
      "mc": {
        "longitude": 133.935705,
        "sign": "Leo",
        "sign_index": 4,
        "degree_in_sign": 13.935705
      },
      "planets": [
        {
          "name": "Sun",
          "longitude": 293.981301,
          "sign": "Capricorn",
          "sign_index": 9,
          "degree_in_sign": 23.981301,
          "house": 3,
          "is_retrograde": false,
          "dignity": "peregrine",
          "dignity_score": 0,
          "is_exaltation_degree": false,
          "dignity_disputed": false
        },
        {
          "name": "Moon",
          "longitude": 94.360866,
          "sign": "Cancer",
          "sign_index": 3,
          "degree_in_sign": 4.360866,
          "house": 8,
          "is_retrograde": false,
          "dignity": "domicile",
          "dignity_score": 5,
          "is_exaltation_degree": false,
          "dignity_disputed": false
        },
        "... and 8 more items"
      ],
      "houses": [
        {
          "house": 1,
          "cusp_longitude": 223.233989,
          "sign": "Scorpio",
          "sign_index": 7,
          "degree_in_sign": 13.233989
        },
        {
          "house": 2,
          "cusp_longitude": 252.439351,
          "sign": "Sagittarius",
          "sign_index": 8,
          "degree_in_sign": 12.439351
        },
        "... and 10 more items"
      ],
      "aspects": [
        {
          "planet_a": "Jupiter",
          "planet_b": "Pluto",
          "type": "conjunction",
          "exact_angle": 4.56,
          "orb": 4.56,
          "is_applying": true
        },
        {
          "planet_a": "Jupiter",
          "planet_b": "Venus",
          "type": "semisextile",
          "exact_angle": 31.4267,
          "orb": 1.4267,
          "is_applying": false
        },
        "... and 8 more items"
      ],
      "elements": {
        "fire": 1,
        "earth": 2,
        "air": 3,
        "water": 4,
        "dominant": "water"
      },
      "modalities": {
        "cardinal": 5,
        "fixed": 3,
        "mutable": 2,
        "dominant": "cardinal"
      },
      "hemisphere": {
        "eastern": 3,
        "western": 7,
        "northern": 7,
        "southern": 3
      },
      "ayanamsa_value": 0.0,
      "ayanamsa_used": "tropical",
      "birth_time_provided": true
    }
  }
}

Response fields

Field	Type	Description
success	boolean	True if the request succeeded
message	string	Human-readable status message
data	object
data.planet	string
data.natal_longitude	number	Natal longitude of the return planet (tropical)
data.return_utc	string	Exact UTC moment of return (ISO 8601)
data.return_jd	number	Julian Day of return moment
data.chart	object
data.chart.zodiac	string	Always 'tropical' for Western natal
data.chart.house_system	string	House system used
data.chart.ascendant	object
data.chart.ascendant.longitude	number	Tropical ecliptic longitude 0–360°
data.chart.ascendant.sign	string	Zodiac sign name
data.chart.ascendant.sign_index	integer	Sign index 0=Aries … 11=Pisces
data.chart.ascendant.degree_in_sign	number	Degrees within sign 0–29.999
data.chart.mc	object
data.chart.mc.longitude	number	Tropical ecliptic longitude 0–360°
data.chart.mc.sign	string	Zodiac sign name
data.chart.mc.sign_index	integer	Sign index 0=Aries … 11=Pisces
data.chart.mc.degree_in_sign	number	Degrees within sign 0–29.999
data.chart.planets	array[object]
data.chart.planets[].name	string	Planet name
data.chart.planets[].longitude	number	Tropical ecliptic longitude 0–360°
data.chart.planets[].sign	string	Zodiac sign name
data.chart.planets[].sign_index	integer
data.chart.planets[].degree_in_sign	number	Degrees within sign 0–29.999
data.chart.planets[].house	integer	House number (Placidus or chosen system)
data.chart.planets[].is_retrograde	boolean
data.chart.planets[].dignity	string	Essential dignity: domicile \| exaltation \| detriment \| fall \| peregrine
data.chart.planets[].dignity_score	integer	Essential dignity weight: domicile=5, exaltation=4, detriment=-5, fall=-4, peregrine=0
data.chart.planets[].is_exaltation_degree	boolean	True if planet is in the exact classical exaltation degree (Nth degree = N-1°00' to N-1°59'59"). Always false for outer planets (no exact degree defined).
data.chart.planets[].dignity_disputed	boolean	True for outer planet (Uranus/Neptune/Pluto) exaltation/fall — no classical consensus.
data.chart.houses	array[object]
data.chart.houses[].house	integer
data.chart.houses[].cusp_longitude	number	Tropical ecliptic longitude of house cusp
data.chart.houses[].sign	string
data.chart.houses[].sign_index	integer
data.chart.houses[].degree_in_sign	number
data.chart.aspects	array[object]
data.chart.aspects[].planet_a	string
data.chart.aspects[].planet_b	string
data.chart.aspects[].type	string	Aspect type: conjunction \| opposition \| trine \| square \| sextile \| semisextile \| semisquare \| sesquiquadrate \| quincunx
data.chart.aspects[].exact_angle	number	Actual angular distance between planets
data.chart.aspects[].orb	number	Difference from exact aspect angle (always positive)
data.chart.aspects[].is_applying	boolean	True if the faster planet is moving toward exact aspect (orb decreasing).
data.chart.elements	object
data.chart.elements.fire	integer
data.chart.elements.earth	integer
data.chart.elements.air	integer
data.chart.elements.water	integer
data.chart.elements.dominant	string \| null	Most common element, or null if tied
data.chart.modalities	object
data.chart.modalities.cardinal	integer
data.chart.modalities.fixed	integer
data.chart.modalities.mutable	integer
data.chart.modalities.dominant	string \| null
data.chart.hemisphere	object
data.chart.hemisphere.eastern	integer	Planet count in houses 7–12
data.chart.hemisphere.western	integer	Planet count in houses 1–6
data.chart.hemisphere.northern	integer	Planet count in houses 1–6 (below horizon)
data.chart.hemisphere.southern	integer	Planet count in houses 7–12 (above horizon)
data.chart.ayanamsa_value	number	Always 0.0 — tropical zodiac
data.chart.ayanamsa_used	string
data.chart.birth_time_provided	boolean	Whether a precise birth time was provided. False when birth time was not supplied or treated as unknown — calculations using this field will have lagna-dependent accuracy limits.

Errors

Code	Description	Reference
authentication_failed	Missing or invalid API key.	authentication_failed
ephemeris_unavailable	Upstream ephemeris service error.	ephemeris_unavailable
insufficient_tier	API key tier does not include this endpoint.	insufficient_tier
internal_error	Unexpected server error.	internal_error
ip_rate_limit_exceeded	Too many requests in a short window.	ip_rate_limit_exceeded
payload_too_large	Request body exceeds the size limit.	payload_too_large
resource_not_found	Referenced resource was not found.	resource_not_found
validation_error	Request body failed schema validation.	validation_error

Endpoint​

Request parameters​

Example request​

Example response​

Response fields​

Errors​

Related endpoints​