---
title: "Western Planetary Return"
method: POST
path: "/v1/western/planetary-return"
tags: ["Western Astrology"]
---

# Western Planetary Return

`POST /v1/western/planetary-return`

## Request

- Base URL: `https://api.asterwise.com`
- URL: `https://api.asterwise.com/v1/western/planetary-return`
- Auth: HTTP bearer

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.

## Request body

- PlanetaryReturnRequest
  - `location` string, nullable: 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: Person name associated with the birth record
  - `date` string, required: Birth date in YYYY-MM-DD format
  - `time` string, nullable: Birth time in HH:MM 24-hour format. If omitted, the chart is cast for 06:00 local time (not a sunrise chart) and birth_time_provided is false: houses, the Ascendant, the sect and the Moon's exact degree are then approximate.
  - `latitude` number, nullable: Latitude. Required if location not provided.
  - `longitude` number, nullable: Longitude. Required if location not provided.
  - `timezone` string, nullable: IANA timezone. Required if location not provided (unless utc_offset is given). For dates before the zone adopted a standard time, the birthplace's local mean time (longitude / 15 hours) is used.
  - `utc_offset` string, nullable: Optional explicit UTC offset of the birth time, as ±HH:MM or ±HH:MM:SS (e.g. '+04:51:31' for Bombay mean time). Overrides the offset `timezone` would give. Use it when the birth record states the offset, or for historical local times the IANA database cannot represent.
  - `ayanamsa` 'lahiri' | 'raman' | 'kp' | 'tropical': Ignored on Western endpoints: positions are always tropical (no ayanamsa). Accepted so one birth object can be sent to Vedic and Western endpoints alike.
  - `planet` string, required: Planet name for the return chart
  - `after_date` string, nullable: Find the next return after this date (YYYY-MM-DD). Defaults to today.

## Response `200`

Successful Response

- ApiResponseReturnChartResponse
  - `success` boolean: True if the request succeeded
  - `message` string: Human-readable status message
  - `data` ReturnChartResponse, required
    - `birth_time_provided` boolean: True when a birth time was supplied. False when it was not: the return chart is then cast from a 06:00 natal chart and its houses are approximate.
    - `planet` string, required
    - `natal_longitude` number, required: Natal longitude of the return planet (tropical)
    - `return_utc` string, required: Exact UTC moment of return (ISO 8601)
    - `return_jd` number, required: Julian Day of return moment
    - `chart` WesternNatalResponse, required
      - `zodiac` string: Always 'tropical' for Western natal
      - `house_system` string, required: House system used
      - `ascendant` WesternAngle, required
        - `longitude` number, required: Tropical ecliptic longitude 0–360°
        - `sign` string, required: Zodiac sign name
        - `sign_index` integer, required: Sign index 0=Aries … 11=Pisces
        - `degree_in_sign` number, required: Degrees within sign 0–29.999
      - `mc` WesternAngle, required
        - `longitude` number, required: Tropical ecliptic longitude 0–360°
        - `sign` string, required: Zodiac sign name
        - `sign_index` integer, required: Sign index 0=Aries … 11=Pisces
        - `degree_in_sign` number, required: Degrees within sign 0–29.999
      - `planets` WesternPlanetPosition[], required
        - `name` string, required: Planet name
        - `longitude` number, required: Tropical ecliptic longitude 0–360°
        - `sign` string, required: Zodiac sign name
        - `sign_index` integer, required
        - `degree_in_sign` number, required: Degrees within sign 0–29.999
        - `house` integer, required: House number (Placidus or chosen system)
        - `is_retrograde` boolean, required
        - `dignity` string, required: Primary sign-level essential dignity: domicile | exaltation | detriment | fall | peregrine. 'peregrine' here means no sign-level dignity; triplicity, term and face are not assessed.
        - `dignity_score` integer, required: Weight of the primary sign-level dignity only: domicile=5, exaltation=4, detriment=-5, fall=-4, peregrine=0. Triplicity, term and face are not scored, and the weights are not summed (e.g. Mercury in Virgo scores 5 for domicile, not 5+4). Full traditional scoring is in essential_dignities (natal and return charts).
        - `is_exaltation_degree` boolean, required: 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).
        - `dignity_disputed` boolean, required: True for outer planet (Uranus/Neptune/Pluto) exaltation/fall — no established consensus.
        - `essential_dignities` WesternEssentialDignities: William Lilly's essential dignities (Christian Astrology, 1647, p.104 table).
          - `domicile` integer, required: 5 if the planet is in one of its own signs (houses), else 0
          - `exaltation` integer, required: 4 if the planet is in its exaltation sign (anywhere in the sign), else 0
          - `triplicity` integer, required: 3 if the planet rules the sign's element for the chart's sect, else 0. Lilly's rulers (day/night): fire Sun/Jupiter, earth Venus/Moon, air Saturn/Mercury, water Mars by day and night.
          - `term` integer, required: 2 if the degree is in the planet's term (Ptolemaic terms as printed by Lilly), else 0
          - `face` integer, required: 1 if the degree is in the planet's face (10° decans, Chaldean order), else 0
          - `detriment` integer, required: -5 if the planet is in its detriment, else 0
          - `fall` integer, required: -4 if the planet is in its fall, else 0
          - `peregrine` boolean, required: True when the planet has none of the five dignities (domicile, exaltation, triplicity, term, face) — Lilly's peregrine, scored -5. A planet in detriment or fall with no dignity is also peregrine.
          - `total` integer, required: Sum of all points above plus -5 when peregrine. Dignities add up (Mercury in Virgo: 5 + 4 = 9 before term/face), as do debilities (Mercury in Pisces: -5 - 4). Range -14 to +11.
          - `applicable` boolean, required: False for Uranus, Neptune and Pluto: Lilly's scheme covers only the seven classical planets, so every score is 0 and peregrine is false.
          - `system` 'lilly': Scoring system: William Lilly, Christian Astrology (1647) — table of essential dignities p.104, weights pp.101–103, debilities p.115. Mutual reception and the lunar nodes are not scored.
      - `houses` WesternHouseCusp[], required
        - `house` integer, required
        - `cusp_longitude` number, required: Tropical ecliptic longitude of house cusp
        - `sign` string, required
        - `sign_index` integer, required
        - `degree_in_sign` number, required
      - `aspects` WesternAspect[], required
        - `planet_a` string, required
        - `planet_b` string, required
        - `type` string, required: Aspect type: conjunction | opposition | trine | square | sextile | semisextile | semisquare | sesquiquadrate | quincunx
        - `exact_angle` number, required: Actual angular distance between planets
        - `orb` number, required: Difference from exact aspect angle (always positive)
        - `is_applying` boolean, required: True if the aspect is applying at this instant: the planets' relative motion (instantaneous speeds) is closing the orb toward exactness. False if separating or exact.
      - `elements` WesternElements, required
        - `fire` integer, required
        - `earth` integer, required
        - `air` integer, required
        - `water` integer, required
        - `dominant` string, nullable: Most common element, or null if tied
      - `modalities` WesternModalities, required
        - `cardinal` integer, required
        - `fixed` integer, required
        - `mutable` integer, required
        - `dominant` string, nullable
      - `hemisphere` WesternHemisphere, required
        - `eastern` integer, required: Planet count in houses 10, 11, 12, 1, 2, 3 (the Ascendant side of the MC–IC meridian)
        - `western` integer, required: Planet count in houses 4–9 (the Descendant side of the MC–IC meridian)
        - `northern` integer, required: Planet count in houses 1–6 (below horizon)
        - `southern` integer, required: Planet count in houses 7–12 (above horizon)
      - `ayanamsa_value` number: Always 0.0 — tropical zodiac
      - `ayanamsa_used` string
      - `sect` 'day' | 'night', nullable: Chart sect: 'day' when the Sun is above the horizon, else 'night'. Computed from the Sun's true altitude at the birth place and time (geometric horizon, Sun's centre, no refraction), so it is the same for every house system and stays right above the polar circles (midnight Sun = day). Selects Lilly's triplicity rulers in essential_dignities. Depends on the birth time: with no time supplied it reflects the default 06:00.
      - `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.

## Other responses

- `401`: Authentication failed
- `403`: Authorization failed
- `404`: Resource not found
- `413`: Payload too large
- `422`: Validation error
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream provider error
- `503`: Service unavailable

---

[API](https://skmtc.dev/asterwise/apis/asterwise-api.md) · [All operations](https://skmtc.dev/asterwise/apis/asterwise-api/llms.txt) · [OpenAPI document](https://skmtc.dev/asterwise/apis/asterwise-api/revisions/e77850f7c569?raw)