POST/v1/western/lunar-return

Western Lunar Return

Western lunar return chart: the next moment after a given date that the Moon returns to its natal tropical longitude (about every 27.3 days). The chart is a complete Western natal chart for that moment at the birth location.

Request parameters

locationoptional

string | null

City name to resolve to lat/lon/tz automatically. Example: 'Mumbai' or 'New Delhi, India'. If provided, latitude, longitude and timezone are not required.

nameoptional

string

Person name associated with the birth record

daterequired

string

Birth date in YYYY-MM-DD format

timeoptional

string | null

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.

latitudeoptional

number | null

Latitude. Required if location not provided.

longitudeoptional

number | null

Longitude. Required if location not provided.

timezoneoptional

string | null

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_offsetoptional

string | null

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.

ayanamsaoptional

string

Ignored on Western endpoints: positions are always tropical (no ayanamsa). Accepted so one birth object can be sent to Vedic and Western endpoints alike.

after_dateoptional

string | null

Find the next lunar return after this date (YYYY-MM-DD). Defaults to today.

Response fields

success

boolean

True if the request succeeded

message

string

Human-readable status message

data

object

data.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.

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

Primary sign-level essential dignity: domicile | exaltation | detriment | fall | peregrine. 'peregrine' here means no sign-level dignity; triplicity, term and face are not assessed.

data.chart.planets[].dignity_score

integer

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).

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 established consensus.

data.chart.planets[].essential_dignities

WesternEssentialDignities | null

Traditional essential dignity scoring after William Lilly: domicile +5, exaltation +4, triplicity +3 (by the chart's sect), term +2, face +1, detriment -5, fall -4, peregrine -5, summed in total. Additive to dignity/dignity_score, which are unchanged.

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 aspect is applying at this instant: the planets' relative motion (instantaneous speeds) is closing the orb toward exactness. False if separating or exact.

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 10, 11, 12, 1, 2, 3 (the Ascendant side of the MC–IC meridian)

data.chart.hemisphere.western

integer

Planet count in houses 4–9 (the Descendant side of the MC–IC meridian)

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.sect

string | null

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.

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

api_key_invalid

Invalid API key format.

api_key_missing

API key is missing. Include it in the Authorization header as 'Bearer YOUR_KEY'.

api_key_not_found

The provided API key was not found. Verify the key in your Asterwise dashboard.

api_key_revoked

This API key has been revoked.

burst_limit_exceeded

Too many requests per minute. Please slow down.

internal_error

Something went wrong on our end. Please try again, or contact [email protected] if the problem persists. Include your request_id when contacting support.

ip_rate_limit_exceeded

Too many requests from this IP address. Please slow down.

monthly_usage_limit_exceeded

Monthly API call limit reached. Upgrade your plan to continue.

payload_too_large

Request body exceeds maximum allowed size of 64KB.

subscription_expired

Your subscription has expired. Please renew at asterwise.com/dashboard to continue.

validation_error

The request couldn't be processed. See the 'details' field for specific field-level issues.

Related endpoints

• Western Planetary Return
• Western Solar Return

Request

POST·application/json

curl

curl -X POST "https://api.asterwise.com/v1/western/lunar-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","after_date":"2026-01-01"}'

Python

import asterwise
from asterwise.api.western_astrology_api import WesternAstrologyApi
from asterwise.models.lunar_return_request import LunarReturnRequest

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

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

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

TypeScript

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

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

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

console.log(result.data);

Response

200 OK·application/jsonsigned

{
  "success": true,
  "message": "success",
  "data": {
    "planet": "Moon",
    "natal_longitude": 221.838361,
    "return_utc": "2026-01-12T10:46:09Z",
    "return_jd": 2461052.948725,
    "chart": {
      "zodiac": "tropical",
      "house_system": "placidus",
      "ascendant": {
        "longitude": 85.368402,
        "sign": "Gemini",
        "sign_index": 2,
        "degree_in_sign": 25.368402
      },
      "mc": {
        "longitude": 345.190957,
        "sign": "Pisces",
        "sign_index": 11,
        "degree_in_sign": 15.190957
      },
      "planets": [
        {
          "name": "Sun",
          "longitude": 292.233427,
          "sign": "Capricorn",
          "sign_index": 9,
          "degree_in_sign": 22.233427,
          "house": 8,
          "is_retrograde": false,
          "dignity": "peregrine",
          "dignity_score": 0,
          "is_exaltation_degree": false,
          "dignity_disputed": false,
          "essential_dignities": {
            "domicile": 0,
            "exaltation": 0,
            "triplicity": 0,
            "term": 0,
            "face": 1,
            "detriment": 0,
            "fall": 0,
            "peregrine": false,
            "total": 1,
            "applicable": true,
            "system": "lilly"
          }
        },
        {
          "name": "Moon",
          "longitude": 221.838361,
          "sign": "Scorpio",
          "sign_index": 7,
          "degree_in_sign": 11.838361,
          "house": 5,
          "is_retrograde": false,
          "dignity": "fall",
          "dignity_score": -4,
          "is_exaltation_degree": false,
          "dignity_disputed": false,
          "essential_dignities": {
            "domicile": 0,
            "exaltation": 0,
            "triplicity": 0,
            "term": 0,
            "face": 0,
            "detriment": 0,
            "fall": -4,
            "peregrine": true,
            "total": -9,
            "applicable": true,
            "system": "lilly"
          }
        },
        "... and 8 more items"
      ],
      "houses": [
        {
          "house": 1,
          "cusp_longitude": 85.368402,
          "sign": "Gemini",
          "sign_index": 2,
          "degree_in_sign": 25.368402
        },
        {
          "house": 2,
          "cusp_longitude": 110.060876,
          "sign": "Cancer",
          "sign_index": 3,
          "degree_in_sign": 20.060876
        },
        "... and 10 more items"
      ],
      "aspects": [
        {
          "planet_a": "Jupiter",
          "planet_b": "Mars",
          "type": "opposition",
          "exact_angle": 178.322,
          "orb": 1.678,
          "is_applying": false
        },
        {
          "planet_a": "Jupiter",
          "planet_b": "Mercury",
          "type": "opposition",
          "exact_angle": 176.6964,
          "orb": 3.3036,
          "is_applying": true
        },
        "... and 11 more items"
      ],
      "elements": {
        "fire": 0,
        "earth": 5,
        "air": 1,
        "water": 4,
        "dominant": "earth"
      },
      "modalities": {
        "cardinal": 5,
        "fixed": 3,
        "mutable": 2,
        "dominant": "cardinal"
      },
      "hemisphere": {
        "eastern": 4,
        "western": 6,
        "northern": 2,
        "southern": 8
      },
      "ayanamsa_value": 0.0,
      "ayanamsa_used": "tropical",
      "sect": "day",
      "birth_time_provided": true
    }
  }
}