Solar Return Chart (Western)

POST/api/v1/western/solar/calculate

Generate high-precision Solar Return charts. The engine automatically uses an iterative search window to find the exact sub-millisecond moment the Sun returns to its precise natal position, and natively compiles standard chart blocks alongside a custom natal comparison schema including cross-chart aspects and house overlays.

The solar route remains backward compatible as the Sun-specific wrapper. For Moon and other planetary returns, use the Planetary Return docs and the generic /api/v1/western/returns/calculate endpoint.

Both return endpoints support sidereal calculations through settings.zodiac_type and settings.sidereal_ayanamsa.

Unknown birth time? Set natal.time_known to false. The default single_moment mode preserves the legacy noon-based response. For the astrologically safer result, explicitly set solar_return.calculation_mode to uncertainty_range; only that mode suppresses houses, angles, angularity, and natal house overlays.

Full URL

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

Parameters

The request body has two top-level objects: natal and solar_return. Optional calculation settings belong inside solar_return.settings, not at the root.

The natal object accepts either a backward-compatible datetime string or Natal-style split fields like year/month/day/hour/minute. Naive local birth times are interpreted in natal.location.timezone or AUTO resolution, matching Natal endpoint behavior.

natal (Object)

Parameter	Type	Req	Description
name	string	No	Display name for the natal subject.
datetime	string	No	Backward-compatible natal birth datetime. Supports 'YYYY-MM-DD HH:MM' and ISO 8601 forms.
year	integer	No	Natal birth year. Use with month/day when not sending datetime.
month	integer	No	Natal birth month. Use with year/day when not sending datetime.
day	integer	No	Natal birth day. Use with year/month when not sending datetime.
hour	integer	No	Natal birth hour. Default: 12 when omitted.
minute	integer	No	Natal birth minute. Default: 0 when omitted.
time_known	boolean	No	Default true. Set false for an unknown birth time. The default single_moment mode retains the legacy local-noon chart data; uncertainty_range suppresses time-sensitive factors.
location.timezone	string	No	Birth timezone string. Alias: tz_str. Default: AUTO.
location.city	string	Yes	Birth city. Used for coordinate lookup if lat/lng are omitted.
location.lat	float	No	Birth latitude (optional if city is provided).
location.lng	float	No	Birth longitude (optional if city is provided).

solar_return (Object)

Parameter	Type	Req	Description
year	integer	Yes	The target year for the Solar Return (e.g. 2024).
calculation_mode	string	No	'single_moment' (default) or 'uncertainty_range'. Range mode requires time_known=false plus natal year/month/day.
location.city	string	Yes	Return city (used for coordinate lookup if lat/lng are omitted).
location.lat	float	No	Return latitude (optional if city is provided).
location.lng	float	No	Return longitude (optional if city is provided).
location.timezone	string	No	Return timezone. Default: AUTO.
settings	object	No	Optional calculation settings nested inside solar_return.

solar_return.settings (Object, Optional)

Parameter	Type	Req	Description
house_system	string	No	Default 'placidus'.
zodiac_type	string	No	'Tropical' or 'Sidereal'. Default 'Tropical'.
sidereal_ayanamsa	string	No	Optional for sidereal mode. Defaults to 'lahiri' when zodiac_type is 'Sidereal'.
coordinate_system	string	No	Default 'geocentric_ecliptic'.
node_type	string	No	'true' or 'mean'. Default 'true'.
aspect_set	string	No	'major' or 'major+minor'. Default 'major'.
include_aspects	boolean	No	Generate aspects between planets in the solar return chart. Default true.
include_natal_comparison	boolean	No	Generate cross-chart aspects from return planets to natal planets. Default true.
include_house_overlay	boolean	No	Calculate which natal houses the solar return planets fall into. Default true.
orb_policy	object	No	Custom orb constraints. See Synastry documentation for schema structure.

Unknown Birth Time

uncertainty_range treats the possible birth time as the complete local birth date, from 00:00:00 through 23:59:59.999999 in the natal timezone. It calculates the solar return at both boundaries and keeps the existing noon result only as a representative reference chart.

The response samples 25 moments across the possible return window and reports each planet's observed movement. A position is listed in stable_factors only when every sample remains in the same sign and the total sampled span is no more than 1 degree. Aspects are marked as not range-verified; houses, angles, angularity, and natal house overlays are suppressed.

Request

{
  "natal": {
    "name": "Untimed User",
    "year": 1990,
    "month": 1,
    "day": 1,
    "time_known": false,
    "location": {
      "city": "London"
    }
  },
  "solar_return": {
    "year": 2026,
    "calculation_mode": "uncertainty_range",
    "location": {
      "city": "Paris"
    }
  }
}

Response excerpt

{
  "meta": {
    "solar_return": {
      "target_year": 2026,
      "exact_moment_utc": "2026-01-01T...Z",
      "calculation_mode": "uncertainty_range",
      "confidence": "approximate",
      "reference_chart_basis": "local_noon",
      "uncertainty": {
        "possible_return_start_utc": "2026-01-01T...Z",
        "possible_return_end_utc": "2026-01-02T...Z",
        "window_hours": 24.01,
        "position_stability_threshold_deg": 1.0,
        "position_sample_count": 25,
        "planet_position_ranges": [
          {
            "body": "moon",
            "start_abs_pos": 172.1,
            "end_abs_pos": 184.4,
            "span_deg": 12.3,
            "same_sign": false,
            "stable": false
          }
        ],
        "stable_factors": ["jupiter_position", "saturn_position"],
        "unstable_factors": [
          "moon_position",
          "aspects_not_range_verified",
          "return_houses",
          "return_angles"
        ],
        "suppressed_fields": [
          "houses",
          "angles",
          "angles_details",
          "planets[].house",
          "natal_comparison.house_overlay",
          "natal_comparison.angularity"
        ]
      }
    }
  },
  "houses": [],
  "angles": {},
  "angles_details": {}
}

Generic Planetary Returns

The generic endpoint covers Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto returns. Fast-moving bodies can produce multiple valid hits near the same window, especially around retrograde periods, so the request uses a date anchor plus a selection mode instead of a year-only selector.

Parameter	Type	Req	Description
return_target.body	string	Yes	One of sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto.
return_target.search_start	string	Yes	ISO datetime anchor used to search for the desired return event.
return_target.selection_mode	string	No	nearest, next, or previous. Default nearest.
return_target.location.city	string	Yes	Return chart city used for coordinate lookup if lat/lng are omitted.
meta.return_event	object	Yes	Generic event metadata including body, exact moment, target_longitude_abs, and target_error_arcsec.

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": {
        "name": "User",
        "datetime": "1994-04-15 10:30",
        "location": {
            "city": "London",
            "lat": 51.5074,
            "lng": -0.1278
        }
    },
    "return_target": {
        "body": "moon",
        "search_start": "2024-05-01T00:00:00Z",
        "selection_mode": "nearest",
        "location": {
            "city": "Paris",
            "lat": 48.8566,
            "lng": 2.3522
        }
    }
}'

Minimal Real Request

Minimal tropical request:

{
  "natal": {
    "name": "Test User",
    "datetime": "1990-01-01 12:00",
    "location": {
      "city": "London"
    }
  },
  "solar_return": {
    "year": 2024,
    "location": {
      "city": "New York",
      "lat": 40.7128,
      "lng": -74.0060,
      "timezone": "America/New_York"
    }
  }
}

Minimal sidereal request. Lahiri is now the default, so sidereal_ayanamsa can be omitted:

{
  "natal": {
    "name": "Test User",
    "datetime": "1990-01-01 12:00",
    "location": {
      "city": "London"
    }
  },
  "solar_return": {
    "year": 2024,
    "location": {
      "city": "New York",
      "lat": 40.7128,
      "lng": -74.0060,
      "timezone": "America/New_York"
    },
    "settings": {
      "zodiac_type": "Sidereal"
    }
  }
}

To force a specific sidereal ayanamsa, pass it inside solar_return.settings, for example "sidereal_ayanamsa": "lahiri".

Request Example

curl -X POST "https://api.freeastroapi.com/api/v1/western/solar/calculate" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
    "natal": {
        "name": "Test User",
        "year": 1990,
        "month": 1,
        "day": 1,
        "hour": 12,
        "minute": 0,
        "time_known": true,
        "location": {
            "city": "London"
        }
    },
    "solar_return": {
        "year": 2024,
        "location": {
            "city": "New York",
            "lat": 40.7128,
            "lng": -74.0060,
            "timezone": "America/New_York"
        },
        "settings": {
            "zodiac_type": "Sidereal"
        }
    }
}'

Response Format

The response closely matches standard Natal generation pipelines with an extended meta.solar_return root defining exact calculated hits. It also optionally attaches natal_comparison arrays linking back to the origin chart.

For unknown birth times, exact_moment_utc is the local-noon reference, not a claim of birth-time precision. Check confidence and the optional uncertainty object before interpreting the chart.

{
  "meta": {
    "report_id": "c5ff579e-...",
    "calculation": {
      "zodiac_type": "Tropical",
      "house_system": "placidus",
      "aspect_set": "major"
    },
    "solar_return": {
      "target_year": 2024,
      "exact_moment_utc": "2024-04-15T01:45:10.123456Z",
      "exact_moment_local": "2024-04-15T03:45:10.123456+02:00",
      "sun_target_longitude_abs": 25.12318041,
      "sun_error_arcsec": 0.003,
      "calculation_mode": "single_moment",
      "confidence": "exact",
      "reference_chart_basis": "exact_birth_time",
      "uncertainty": null
    }
  },
  "subject": {
    "name": "User - Solar Return 2024",
    "datetime": "2024-04-15T03:45:10.123456+02:00",
    "location": {
      "city": "Paris",
      "timezone": "Europe/Paris"
    }
  },
  "planets": [...],
  "houses": [...],
  "angles": {...},
  "natal_comparison": {
    "aspects": [
      {
        "sr_body": "sun",
        "natal_body": "sun",
        "type": "conjunction",
        "orb": 0.0,
        "deg": 0.0,
        "is_major": true
      }
    ],
    "house_overlay": [
      {
        "sr_body": "sun",
        "natal_house": 12
      }
    ]
  }
}