ephemeris_solar_return
Read-onlyIdempotent
Calculate the precise Solar Return date/time when the Sun returns to its natal longitude and obtain the Solar Return chart for the year ahead.
Instructions
Calculate the exact Solar Return date/time — when the Sun returns to its natal ecliptic longitude (happens once per year near the birthday). Returns the Solar Return chart for the year ahead.
CREDIT COST: 5 credits per call.
TARGET DATE: Provide target_datetime near the desired birthday year. If omitted, defaults to the current year's solar return.
EXAMPLE: Solar return for someone born 1985-06-21 (current year): birth_datetime='1985-06-21T14:00:00Z'
EXAMPLE: Solar return for 2027 specifically: birth_datetime='1985-06-21T14:00:00Z', target_datetime='2027-01-01T00:00:00Z'
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| timezone | No | IANA timezone (e.g. `America/Chicago`); required when the datetime is naive, ignored otherwise. | |
| visual_config | No | Optional rendering preferences (only used when include_visual=true). | |
| birth_datetime | Yes | ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`. | |
| birth_latitude | No | Birth latitude in decimal degrees (optional, for location context). | |
| include_visual | No | When true, renders the solar return chart wheel as an SVG and embeds it in the response. The chart image will display in the conversation alongside the data. Costs 2 additional credits on top of the base call cost. | |
| birth_longitude | No | Birth longitude in decimal degrees (optional, for location context). | |
| return_latitude | No | Location latitude for the return chart (optional, if different from birth location). | |
| target_datetime | No | Date/time near which to find the Solar Return (ISO 8601 with offset or Z). Defaults to approximately 1 year from now if omitted. | |
| return_longitude | No | Location longitude for the return chart (optional). |