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 as SVG or PNG. The API finds the exact instant when the transiting Sun returns to its natal longitude, then calculates the outer wheel for the requested year and return location.

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
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.
Field
show_inter_aspects
Type
boolean
Required
No
Description
Draw solar-return-to-natal aspect lines. Defaults to true.
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.
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

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)

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.

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.
  • 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.

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.

SVG Natal Chart

Full reference for display_settings and chart_config.