Solar Return Chart (Western)

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.

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)

solar_return (Object)

solar_return.settings (Object, Optional)

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.

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

{
  "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"
    }
  }
}

{
  "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"
    }
  }
}

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"
        }
    },
    "settings": {
        "zodiac_type": "Sidereal",
        "sidereal_ayanamsa": "lahiri"
    }
}'

Response Format

{
  "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
    }
  },
  "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
      }
    ]
  }
}