Back to Docs
SVG Solar Return Chart

SVG Solar Return Chart

POST/api/v1/natal/chart/solar-return

Render a natal and solar-return bi-wheel, or a solar-return-only chart, as SVG or PNG. The API finds the exact instant when the transiting Sun returns to its natal longitude, then calculates the return chart for the requested year and location.

For an unknown birth time, set natal.time_known to false. The default single_moment mode remains backward compatible. Explicit uncertainty_range mode calculates a possible return window and embeds the uncertainty data in the rendered result.

Full URL

https://api.freeastroapi.com/api/v1/natal/chart/solar-return

Request fields

The return location accepts either a city or a complete latitude/longitude pair.

Field
natal
Type
object
Required
Yes
Description
Birth data and the shared SVG/PNG rendering configuration.
Field
solar_return_year
Type
integer
Required
Yes
Description
Target year for the exact solar return (1-9999).
Field
chart_mode
Type
"biwheel" | "solar_return_only"
Required
No
Description
Defaults to "biwheel". Use "solar_return_only" for one wheel containing only return planets, houses, and angles. Birth data is still required to calculate the return instant.
Field
calculation_mode
Type
"single_moment" | "uncertainty_range"
Required
No
Description
Defaults to "single_moment". Range mode requires natal.time_known=false and evaluates the complete local birth date.
Field
solar_return_city
Type
string
Required
No
Description
City where the person will spend the solar return. Required unless both return coordinates are supplied.
Field
solar_return_lat
Type
float
Required
No
Description
Solar-return latitude. Supply it together with solar_return_lng when the city is omitted.
Field
solar_return_lng
Type
float
Required
No
Description
Solar-return longitude. Supply it together with solar_return_lat when the city is omitted.
Field
solar_return_tz_str
Type
string
Required
No
Description
IANA timezone for the return location. Defaults to "AUTO".
Field
show_natal_aspects
Type
boolean
Required
No
Description
Draw natal-to-natal aspect lines. Defaults to false. Ignored in solar_return_only mode.
Field
show_inter_aspects
Type
boolean
Required
No
Description
Draw solar-return-to-natal aspect lines. Defaults to true. Ignored in solar_return_only mode.
Field
show_solar_return_aspects
Type
boolean
Required
No
Description
Draw aspects within the solar-return chart. Defaults to false.
Field
natal_planet_color
Type
string | null
Required
No
Description
Natal-ring color. Defaults to "#1565C0"; null uses body colors.
Field
solar_return_planet_color
Type
string | null
Required
No
Description
Solar-return-ring color. Defaults to "#C62828"; null uses body colors.
Field
chart_config
Type
object
Required
No
Description
Top-level visual overrides merged after natal.chart_config, matching the SVG transit endpoint.

Natal object

The nested natal object uses the same birth-data and visual configuration contract as the SVG transit endpoint.

Field
name
Type
string
Required
No
Description
Display name. Defaults to "User".
Field
year
Type
integer
Required
Yes
Description
Birth year.
Field
month
Type
integer
Required
Yes
Description
Birth month (1-12).
Field
day
Type
integer
Required
Yes
Description
Birth day (1-31).
Field
hour
Type
integer
Required
No
Description
Birth hour (0-23). Defaults to 12.
Field
minute
Type
integer
Required
No
Description
Birth minute (0-59). Defaults to 0.
Field
time_known
Type
boolean
Required
No
Description
Whether the birth time is known. Defaults to true. Set false before requesting uncertainty_range.
Field
city
Type
string
Required
No
Description
Birth city. Required unless lat and lng are both supplied.
Field
lat
Type
float
Required
No
Description
Birth latitude; provide it together with lng.
Field
lng
Type
float
Required
No
Description
Birth longitude; provide it together with lat.
Field
tz_str
Type
string
Required
No
Description
Birth timezone. Defaults to "AUTO".
Field
format
Type
"svg" | "png"
Required
No
Description
Response format. Defaults to "svg".
Field
size
Type
integer
Required
No
Description
Square chart size in pixels. Defaults to 700.
Field
theme_type
Type
string
Required
No
Description
One of "light", "dark", or "mono".
Field
zodiac_type
Type
string
Required
No
Description
Use "tropical" or "sidereal". Defaults to "tropical".
Field
house_system
Type
string
Required
No
Description
House system used by both wheels. Defaults to "placidus".
Field
display_settings
Type
object
Required
No
Description
Body and angle visibility controls shared with the natal and transit SVG endpoints.
Field
chart_config
Type
object
Required
No
Description
Detailed ring geometry, colors, glyph sizes, labels, backgrounds, and line styles.

cURL example

curl -X POST "https://api.freeastroapi.com/api/v1/natal/chart/solar-return" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "natal": {
      "name": "Maya",
      "year": 1990,
      "month": 5,
      "day": 15,
      "hour": 14,
      "minute": 30,
      "city": "London",
      "tz_str": "AUTO",
      "format": "svg",
      "size": 700,
      "theme_type": "light"
    },
    "solar_return_year": 2026,
    "solar_return_city": "Paris",
    "solar_return_tz_str": "AUTO",
    "show_inter_aspects": true,
    "show_natal_aspects": false,
    "show_solar_return_aspects": false,
    "natal_planet_color": "#1565C0",
    "solar_return_planet_color": "#C62828"
  }' \
  --output solar_return_2026.svg

To show only the solar return, add these fields to the same request. Return aspects remain off by default; this example enables them. The wheel uses the return location's houses and angles.

{
  "chart_mode": "solar_return_only",
  "show_solar_return_aspects": true
}

Python example

import requests

response = requests.post(
    "https://api.freeastroapi.com/api/v1/natal/chart/solar-return",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "natal": {
            "name": "Maya",
            "year": 1990,
            "month": 5,
            "day": 15,
            "hour": 14,
            "minute": 30,
            "city": "London",
            "tz_str": "AUTO",
            "format": "svg",
        },
        "solar_return_year": 2026,
        "solar_return_city": "Paris",
        "solar_return_tz_str": "AUTO",
        "show_inter_aspects": True,
    },
)
response.raise_for_status()

with open("solar_return_2026.svg", "wb") as output:
    output.write(response.content)

Unknown birth time

uncertainty_range treats the unknown time as the complete local birth date. It calculates the possible Solar Return boundaries and samples 25 moments across that window. The displayed planets use the local-noon reference moment.

Untimed SVG charts hide houses and angles. Planetary house assignments, angularity, and natal house overlays are not presented as reliable factors. Requested aspect lines remain a representative snapshot and are marked aspects_not_range_verified in the uncertainty metadata.

The visible chart metadata labels both the birth time and return time as unknown and includes the calculated window length in the Solar Return heading.

curl -X POST "https://api.freeastroapi.com/api/v1/natal/chart/solar-return" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -D solar_return_range_headers.txt \
  -d '{
    "natal": {
      "name": "Untimed chart",
      "year": 1990,
      "month": 1,
      "day": 1,
      "time_known": false,
      "city": "London",
      "tz_str": "Europe/London",
      "format": "svg"
    },
    "solar_return_year": 2026,
    "calculation_mode": "uncertainty_range",
    "solar_return_city": "Paris",
    "solar_return_tz_str": "Europe/Paris"
  }' \
  --output solar_return_range_2026.svg

Response

A successful SVG request returns 200 image/svg+xml with an inline filename such as solar_return_2026.svg. Set natal.format to png for image/png.

Solar Return response headers

Field
X-Solar-Return-Chart-Mode
Type
string
Required
Yes
Description
The rendered layout: "biwheel" or "solar_return_only".
Field
X-Solar-Return-Calculation-Mode
Type
string
Required
Yes
Description
The resolved mode: "single_moment" or "uncertainty_range".
Field
X-Solar-Return-Confidence
Type
string
Required
Yes
Description
"exact" for a known birth time or "approximate" for an unknown one.
Field
X-Solar-Return-Reference-Chart-Basis
Type
string
Required
Yes
Description
"exact_birth_time" or "local_noon".
Field
X-Solar-Return-Uncertainty
Type
JSON string
Required
No
Description
The complete uncertainty object in range mode. Available for both SVG and PNG responses and exposed through CORS.

Embedded SVG metadata

In range mode, SVG output contains the complete calculation metadata under the following element. PNG clients can read the same uncertainty object from the response header.

<metadata
  id="freeastroapi-solar-return-uncertainty"
  type="application/json"
>
  {
    "solar_return": {
      "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_sample_count": 25,
        "planet_position_ranges": [],
        "stable_factors": [],
        "unstable_factors": ["aspects_not_range_verified"],
        "suppressed_fields": ["houses", "angles"]
      }
    }
  }
</metadata>

Errors and calculation notes

  • 400 for unresolved birth/return locations or invalid timezone normalization.
  • 422 for schema errors such as a missing year or partial coordinate pair.
  • uncertainty_range returns 422 unless natal.time_known=false.
  • The return is calculated from the natal Sun longitude; it is not approximated from the birthday and birth clock time.
  • Return houses and angles use the solar-return location, while natal houses use the birth location.
  • Omitting calculation_mode preserves the existing single_moment rendering behavior.

Related endpoints

SVG Transit Chart

The same bi-wheel renderer for a caller-supplied transit datetime.

Solar Return JSON

Exact return metadata, positions, aspects, overlays, and angularity as JSON.

Chart Without a Birth Time

What remains reliable when the birth time is unknown.

SVG Natal Chart

Full reference for display_settings and chart_config.