Planetary Return Chart (Western)

POST/api/v1/western/returns/calculate

Generate high-precision planetary return charts for Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, or Pluto. The endpoint finds the exact return moment for the requested natal body, then returns a full relocated chart plus natal comparison overlays and aspects.

Sidereal returns are supported through settings.zodiac_type and settings.sidereal_ayanamsa.

Full URL

https://api.freeastroapi.com/api/v1/western/returns/calculate

Parameters

natal (Object)

Parameter	Type	Req	Description
datetime	string	Yes	Natal birth date/time. Supported formats include 'YYYY-MM-DD HH:MM' and ISO timestamps.
location.city	string	Yes	Birth city. Used for coordinate lookup if lat/lng are omitted.
location.lat	float	No	Birth latitude.
location.lng	float	No	Birth longitude.
name	string	No	Display name for the natal subject. Defaults to 'User'.
location.timezone	string	No	Timezone name. Defaults to AUTO.

return_target (Object)

Parameter	Type	Req	Description
body	string	Yes	One of sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto.
search_start	string	Yes	ISO datetime anchor used to search for the desired return event.
location.city	string	Yes	Return chart city. Used for coordinate lookup if lat/lng are omitted.
location.lat	float	No	Return latitude.
location.lng	float	No	Return longitude.
selection_mode	string	No	nearest, next, or previous. Default nearest.
location.timezone	string	No	Timezone name. Defaults to AUTO.

settings (Object, Optional)

Parameter	Type	Req	Description
zodiac_type	string	No	'Tropical' or 'Sidereal'. Default 'Tropical'.
sidereal_ayanamsa	string	No	When zodiac_type is Sidereal: lahiri, raman, kp, fagan_bradley, or yukteshwar.
house_system	string	No	Default 'placidus'.
coordinate_system	string	No	Default 'geocentric_ecliptic'.
node_type	string	No	'true' or 'mean'. Default 'true'.
bodies	array<string>	No	Bodies included in natal comparison filtering.
aspect_set	string	No	'major' or 'major+minor'. Default 'major'.
orb_policy	object	No	Custom orb constraints. See Synastry documentation for schema structure.
include_aspects	boolean	No	Generate aspects inside the return chart. Default true.
include_natal_comparison	boolean	No	Generate return-to-natal comparison blocks. Default true.
include_house_overlay	boolean	No	Calculate natal house overlays for return planets. Default true.

Request Example

curl -X POST "https://api.freeastroapi.com/api/v1/western/returns/calculate" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
    "natal": {
        "datetime": "1990-01-01 12:00",
        "location": {
            "city": "London",
            "lat": 51.5074,
            "lng": -0.1278
        }
    },
    "return_target": {
        "body": "moon",
        "search_start": "2024-05-15T00:00:00Z",
        "location": {
            "city": "Paris",
            "lat": 48.8566,
            "lng": 2.3522
        }
    },
    "settings": {
        "zodiac_type": "Sidereal",
        "sidereal_ayanamsa": "lahiri"
    }
}'

Response Format

The response follows the same core chart structure as the natal endpoint and adds a generic meta.return_event block plus natal_comparison keys using return_body instead of the legacy solar-only naming.

{
  "meta": {
    "report_id": "1bd99459-e570-4412-b692-fd756f195609",
    "calculation": {
      "zodiac_type": "Tropical",
      "house_system": "placidus",
      "aspect_set": "major"
    },
    "return_event": {
      "body": "moon",
      "selection_mode": "next",
      "search_start": "2024-05-15T00:00:00Z",
      "exact_moment_utc": "2024-05-30T06:07:41.962008Z",
      "exact_moment_local": "2024-05-30T08:07:41.962008+02:00",
      "target_longitude_abs": 333.2676545335762,
      "target_error_arcsec": 0.25221229541330104
    },
    "natal_reference": {
      "natal_target_abs_pos": 333.2676545335762
    }
  },
  "subject": {
    "name": "Live Test User - Moon Return",
    "datetime": "2024-05-30T08:07:41.962008+02:00",
    "location": {
      "city": "Paris",
      "timezone": "Europe/Paris"
    }
  },
  "planets": [...],
  "houses": [...],
  "angles": {...},
  "natal_comparison": {
    "aspects": [
      {
        "return_body": "moon",
        "natal_body": "moon",
        "type": "conjunction",
        "orb": 0.0,
        "deg": 0.0,
        "is_major": true
      }
    ],
    "house_overlay": [
      {
        "return_body": "moon",
        "natal_house": 7
      }
    ]
  }
}