1
Resolve the location
curl "https://roxyapi.com/api/v2/location/search?q=New York" \
-H "X-API-Key: YOUR_KEY"
# -> cities[0]: { latitude, longitude, timezone: "America/New_York" }Solar Return API
Annual birthday forecast with relocated chart
POST
/astrology/solar-returnPOST /astrology/lunar-returnPOST /astrology/planetary-returnsIncluded with every plan (at no extra cost)
Generate a solar return chart for any year, the foundational technique for annual astrological forecasting. The chart is cast for the exact moment the transiting Sun returns to its natal ecliptic longitude (your astrological birthday). Returns full tropical zodiac chart with planetary positions, house cusps, aspects, Ascendant, and Midheaven. Location-sensitive: relocating your solar return chart to a different city changes the houses and Ascendant. Solar return chart API, annual horoscope forecast, birthday chart calculator, yearly astrology prediction, relocated solar return.
Location first, chart second
The Solar Return API needs latitude, longitude, and timezone. Never ask users to type coordinates. Resolve a city with the Location endpoint first, then feed the result into the request. Timezone accepts a decimal offset or an IANA name.
2
Call the Solar Return endpoint
# feed latitude, longitude and timezone from step 1
POST https://roxyapi.com/api/v2/astrology/solar-returnRequest
POST /api/v2/astrology/solar-return
Parameters
| Parameter | Type | Description |
|---|---|---|
langquery, optional | string enum | Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default en. |
Request body
| Field | Type | Description |
|---|---|---|
birthDaterequired | string (date) | Original birth date in YYYY-MM-DD format. Used to determine natal Sun longitude for the solar return calculation. |
birthTimerequired | string (time) | Original birth time in 24-hour HH:MM:SS format. Determines exact natal Sun position for annual return timing. |
returnYearrequired | integer | Year for which to cast the solar return chart. The chart is erected for the exact moment the transiting Sun conjuncts the natal Sun longitude in this year. |
latituderequired | number | Latitude of the solar return location in decimal degrees (-90 to 90). Use current residence or travel location at time of birthday. Solar return charts are location-sensitive. |
longituderequired | number | Longitude of the solar return location in decimal degrees (-180 to 180). Affects house cusps and Ascendant of the return chart. |
timezonerequired | number or string | Decimal hours from UTC OR IANA name (e.g. "America/New_York"). IANA resolved to the DST-correct offset for the birthDate. Output datetime is adjusted to this timezone. |
houseSystemoptional | string enum | House system for the solar return chart. Placidus (default) is most common in Western astrology. Whole Sign, Equal, and Koch also supported. |
Example request
{
"birthDate": "1990-07-15",
"birthTime": "14:30:00",
"returnYear": 2026,
"latitude": 40.7128,
"longitude": -74.006,
"timezone": "America/New_York",
"houseSystem": "placidus"
}Response
Structured JSON with documented fields, covered by 13,957 automated tests per deploy, 3,683 of them gold-standard tests verified against NASA JPL Horizons. Not hallucinated text.
{
"birthDate": "1990-07-15",
"solarReturnDate": "2026-07-15T07:19:45",
"solarReturnYear": 2026,
"location": {
"latitude": 40.7128,
"longitude": -74.006,
"timezone": -4
},
"chart": {
"birthDetails": {
"date": "2026-07-15",
"time": "07:19:45",
"latitude": 40.7128,
"longitude": -74.006,
"timezone": -4
},
"planets": [
{
"name": "Sun",
"longitude": 113.00452053395615,
"latitude": 0.00008900879292949334,
"sign": "Cancer",
"degree": 23.004520533956153,
"speed": 0.9543621061583707,
"isRetrograde": false,
"house": 12
},
{
"name": "Moon",
"longitude": 127.8645596741034,
"latitude": 1.975460051938625,
"sign": "Leo",
"degree": 7.864559674103404,
"speed": 14.712040814662686,
"isRetrograde": false,
"house": 12
},
{
"name": "Mercury",
"longitude": 109.19798114829811,
"latitude": -4.928423088724558,
"sign": "Cancer",
"degree": 19.197981148298112,
"speed": -0.5912895915229512,
"isRetrograde": true,
"house": 12
},
{
"name": "Venus",
"longitude": 156.36153954885322,
"latitude": 1.1564580013506274,
"sign": "Virgo",
"degree": 6.361539548853216,
"speed": 1.0988715322290972,
"isRetrograde": false,
"house": 2
},
{
"name": "Mars",
"longitude": 71.73846329382968,
"latitude": -0.12277999339431446,
"sign": "Gemini",
"degree": 11.738463293829682,
"speed": 0.6953735118882776,
"isRetrograde": false,
"house": 11
},
{
"name": "Jupiter",
"longitude": 123.30783693224473,
"latitude": 0.45524365648778514,
"sign": "Leo",
"degree": 3.307836932244726,
"speed": 0.2199579167042458,
"isRetrograde": false,
"house": 12
},
{
"name": "Saturn",
"longitude": 14.640318769438618,
"latitude": -2.4489789003475795,
"sign": "Aries",
"degree": 14.640318769438618,
"speed": 0.019343377097840175,
"isRetrograde": false,
"house": 9
},
{
"name": "Uranus",
"longitude": 64.38277987277321,
"latitude": -0.15551254736874365,
"sign": "Gemini",
"degree": 4.382779872773213,
"speed": 0.042959589070264315,
"isRetrograde": false,
"house": 10
},
{
"name": "Neptune",
"longitude": 4.401023045948071,
"latitude": -1.3791017635106604,
"sign": "Aries",
"degree": 4.401023045948071,
"speed": -0.004295906139347494,
"isRetrograde": true,
"house": 9
},
{
"name": "Pluto",
"longitude": 304.5602866672103,
"latitude": -4.253711682827465,
"sign": "Aquarius",
"degree": 4.560286667210278,
"speed": -0.022830501491228006,
"isRetrograde": true,
"house": 6
},
{
"name": "North Node",
"longitude": 330.2359098783682,
"latitude": 0,
"sign": "Pisces",
"degree": 0.23590987836820432,
"speed": -0.04193401923481588,
"isRetrograde": true,
"house": 7
},
{
"name": "South Node",
"longitude": 150.2359098783682,
"latitude": 0,
"sign": "Virgo",
"degree": 0.23590987836820432,
"speed": -0.04193401923481588,
"isRetrograde": true,
"house": 1
},
{
"name": "Chiron",
"longitude": 30.700215143102586,
"latitude": 0.2584476723799048,
"sign": "Taurus",
"degree": 0.7002151431025858,
"speed": 0.017085735724293727,
"isRetrograde": false,
"house": 9
},
{
"name": "Black Moon Lilith",
"longitude": 263.1532713849792,
"latitude": -4.794194013273138,
"sign": "Sagittarius",
"degree": 23.153271384979178,
"speed": 0.11191699112916353,
"isRetrograde": false,
"house": 5
}
],
"houses": [
{
"number": 1,
"longitude": 132.18987983509504,
"sign": "Leo",
"degree": 12.189879835095041
},
{
"number": 2,
"longitude": 153.32435827549332,
"sign": "Virgo",
"degree": 3.3243582754933243
},
{
"number": 3,
"longitude": 179.28485009574197,
"sign": "Virgo",
"degree": 29.284850095741973
},
{
"number": 4,
"longitude": 211.4122308196901,
"sign": "Scorpio",
"degree": 1.4122308196901088
},
{
"number": 5,
"longitude": 247.68495761453084,
"sign": "Sagittarius",
"degree": 7.684957614530845
},
{
"number": 6,
"longitude": 282.3714501468363,
"sign": "Capricorn",
"degree": 12.37145014683631
},
{
"number": 7,
"longitude": 312.18987983509504,
"sign": "Aquarius",
"degree": 12.189879835095041
},
{
"number": 8,
"longitude": 333.3243582754933,
"sign": "Pisces",
"degree": 3.324358275493296
},
{
"number": 9,
"longitude": 359.28485009574194,
"sign": "Pisces",
"degree": 29.284850095741945
},
{
"number": 10,
"longitude": 31.41223081969011,
"sign": "Taurus",
"degree": 1.4122308196901088
},
{
"number": 11,
"longitude": 67.68495761453084,
"sign": "Gemini",
"degree": 7.684957614530845
},
{
"number": 12,
"longitude": 102.37145014683628,
"sign": "Cancer",
"degree": 12.371450146836281
}
],
"houseSystem": "placidus",
"aspects": [
{
"planet1": "North Node",
"planet2": "South Node",
"type": "OPPOSITION",
"angle": 180,
"orb": 0,
"isApplying": false,
"strength": 100,
"interpretation": "challenging"
},
{
"planet1": "Uranus",
"planet2": "Neptune",
"type": "SEXTILE",
"angle": 60,
"orb": 0.01824317317485935,
"isApplying": true,
"strength": 99.69594711375235,
"interpretation": "harmonious"
},
{
"planet1": "Uranus",
"planet2": "Pluto",
"type": "TRINE",
"angle": 120,
"orb": 0.17750679443707895,
"isApplying": true,
"strength": 97.78116506953651,
"interpretation": "harmonious"
},
{
"planet1": "Neptune",
"planet2": "Pluto",
"type": "SEXTILE",
"angle": 60,
"orb": 0.15926362126219828,
"isApplying": true,
"strength": 97.3456063122967,
"interpretation": "harmonious"
},
{
"planet1": "Sun",
"planet2": "Black Moon Lilith",
"type": "QUINCUNX",
"angle": 150,
"orb": 0.14875085102301,
"isApplying": true,
"strength": 95.041638299233,
"interpretation": "challenging"
},
{
"planet1": "South Node",
"planet2": "Chiron",
"type": "TRINE",
"angle": 120,
"orb": 0.46430526473437794,
"isApplying": false,
"strength": 94.19618419082028,
"interpretation": "harmonious"
},
{
"planet1": "North Node",
"planet2": "Chiron",
"type": "SEXTILE",
"angle": 60,
"orb": 0.46430526473437794,
"isApplying": false,
"strength": 92.2615789210937,
"interpretation": "harmonious"
},
{
"planet1": "Mercury",
"planet2": "Uranus",
"type": "SEMI_SQUARE",
"angle": 45,
"orb": 0.18479872447510104,
"isApplying": false,
"strength": 90.76006377624495,
"interpretation": "challenging"
},
{
"planet1": "Jupiter",
"planet2": "Neptune",
"type": "TRINE",
"angle": 120,
"orb": 1.0931861137033394,
"isApplying": true,
"strength": 86.33517357870826,
"interpretation": "harmonious"
},
{
"planet1": "Moon",
"planet2": "Black Moon Lilith",
"type": "SESQUIQUADRATE",
"angle": 135,
"orb": 0.2887117108757593,
"isApplying": true,
"strength": 85.56441445621203,
"interpretation": "challenging"
},
{
"planet1": "Jupiter",
"planet2": "Pluto",
"type": "OPPOSITION",
"angle": 180,
"orb": 1.252449734965552,
"isApplying": true,
"strength": 84.3443783129306,
"interpretation": "challenging"
},
{
"planet1": "Jupiter",
"planet2": "Uranus",
"type": "SEXTILE",
"angle": 60,
"orb": 1.0749429405284872,
"isApplying": true,
"strength": 82.08428432452521,
"interpretation": "harmonious"
},
{
"planet1": "Venus",
"planet2": "Uranus",
"type": "SQUARE",
"angle": 90,
"orb": 1.9787596760800028,
"isApplying": false,
"strength": 71.73200462742852,
"interpretation": "challenging"
},
{
"planet1": "Saturn",
"planet2": "North Node",
"type": "SEMI_SQUARE",
"angle": 45,
"orb": 0.5955911089295682,
"isApplying": true,
"strength": 70.22044455352159,
"interpretation": "challenging"
},
{
"planet1": "Saturn",
"planet2": "South Node",
"type": "SESQUIQUADRATE",
"angle": 135,
"orb": 0.5955911089295967,
"isApplying": true,
"strength": 70.22044455352017,
"interpretation": "challenging"
},
{
"planet1": "Jupiter",
"planet2": "Chiron",
"type": "SQUARE",
"angle": 90,
"orb": 2.6076217891421436,
"isApplying": false,
"strength": 62.748260155112234,
"interpretation": "challenging"
},
{
"planet1": "Moon",
"planet2": "Pluto",
"type": "OPPOSITION",
"angle": 180,
"orb": 3.3042730068931405,
"isApplying": false,
"strength": 58.69658741383574,
"interpretation": "challenging"
},
{
"planet1": "Moon",
"planet2": "Neptune",
"type": "TRINE",
"angle": 120,
"orb": 3.463536628155339,
"isApplying": false,
"strength": 56.705792148058265,
"interpretation": "harmonious"
},
{
"planet1": "Sun",
"planet2": "Mercury",
"type": "CONJUNCTION",
"angle": 0,
"orb": 3.8065393856580414,
"isApplying": false,
"strength": 52.41825767927448,
"interpretation": "neutral"
},
{
"planet1": "Mars",
"planet2": "Saturn",
"type": "SEXTILE",
"angle": 60,
"orb": 2.90185547560894,
"isApplying": true,
"strength": 51.63574207318433,
"interpretation": "harmonious"
},
{
"planet1": "Moon",
"planet2": "Venus",
"type": "SEMI_SEXTILE",
"angle": 30,
"orb": 1.5030201252501882,
"isApplying": false,
"strength": 49.899329158327056,
"interpretation": "neutral"
},
{
"planet1": "Pluto",
"planet2": "Chiron",
"type": "SQUARE",
"angle": 90,
"orb": 3.8600715241076955,
"isApplying": true,
"strength": 44.85612108417578,
"interpretation": "challenging"
},
{
"planet1": "Moon",
"planet2": "Jupiter",
"type": "CONJUNCTION",
"angle": 0,
"orb": 4.556722741858678,
"isApplying": false,
"strength": 43.04096572676652,
"interpretation": "neutral"
},
{
"planet1": "Moon",
"planet2": "Uranus",
"type": "SEXTILE",
"angle": 60,
"orb": 3.481779801330191,
"isApplying": false,
"strength": 41.97033664449682,
"interpretation": "harmonious"
},
{
"planet1": "Uranus",
"planet2": "North Node",
"type": "SQUARE",
"angle": 90,
"orb": 4.1468699944049945,
"isApplying": false,
"strength": 40.759000079928654,
"interpretation": "challenging"
},
{
"planet1": "Uranus",
"planet2": "South Node",
"type": "SQUARE",
"angle": 90,
"orb": 4.146869994405009,
"isApplying": false,
"strength": 40.75900007992844,
"interpretation": "challenging"
},
{
"planet1": "Venus",
"planet2": "Pluto",
"type": "QUINCUNX",
"angle": 150,
"orb": 1.801252881642938,
"isApplying": false,
"strength": 39.95823727856873,
"interpretation": "challenging"
},
{
"planet1": "Moon",
"planet2": "Mars",
"type": "SEXTILE",
"angle": 60,
"orb": 3.8739036197262777,
"isApplying": true,
"strength": 35.434939671228705,
"interpretation": "harmonious"
},
{
"planet1": "Mercury",
"planet2": "Saturn",
"type": "SQUARE",
"angle": 90,
"orb": 4.55766237885949,
"isApplying": true,
"strength": 34.89053744486442,
"interpretation": "challenging"
},
{
"planet1": "Venus",
"planet2": "Neptune",
"type": "QUINCUNX",
"angle": 150,
"orb": 1.9605165029051363,
"isApplying": false,
"strength": 34.64944990316212,
"interpretation": "challenging"
},
{
"planet1": "Venus",
"planet2": "Chiron",
"type": "TRINE",
"angle": 120,
"orb": 5.661324405750634,
"isApplying": false,
"strength": 29.23344492811708,
"interpretation": "harmonious"
},
{
"planet1": "Venus",
"planet2": "North Node",
"type": "OPPOSITION",
"angle": 180,
"orb": 6.1256296704850115,
"isApplying": false,
"strength": 23.429629118937356,
"interpretation": "challenging"
},
{
"planet1": "Venus",
"planet2": "South Node",
"type": "CONJUNCTION",
"angle": 0,
"orb": 6.1256296704850115,
"isApplying": false,
"strength": 23.429629118937356,
"interpretation": "neutral"
},
{
"planet1": "Venus",
"planet2": "Mars",
"type": "SQUARE",
"angle": 90,
"orb": 5.376923744976466,
"isApplying": true,
"strength": 23.186803643193343,
"interpretation": "challenging"
},
{
"planet1": "Sun",
"planet2": "Venus",
"type": "SEMI_SQUARE",
"angle": 45,
"orb": 1.6429809851029376,
"isApplying": true,
"strength": 17.850950744853122,
"interpretation": "challenging"
},
{
"planet1": "Moon",
"planet2": "Saturn",
"type": "TRINE",
"angle": 120,
"orb": 6.775759095335218,
"isApplying": true,
"strength": 15.303011308309777,
"interpretation": "harmonious"
},
{
"planet1": "South Node",
"planet2": "Black Moon Lilith",
"type": "TRINE",
"angle": 120,
"orb": 7.082638493389027,
"isApplying": true,
"strength": 11.467018832637166,
"interpretation": "harmonious"
},
{
"planet1": "Mars",
"planet2": "Pluto",
"type": "TRINE",
"angle": 120,
"orb": 7.178176626619404,
"isApplying": false,
"strength": 10.27279216725745,
"interpretation": "harmonious"
},
{
"planet1": "Mars",
"planet2": "Uranus",
"type": "CONJUNCTION",
"angle": 0,
"orb": 7.355683421056469,
"isApplying": false,
"strength": 8.05395723679414,
"interpretation": "neutral"
},
{
"planet1": "Chiron",
"planet2": "Black Moon Lilith",
"type": "TRINE",
"angle": 120,
"orb": 7.546943758123405,
"isApplying": true,
"strength": 5.6632030234574415,
"interpretation": "harmonious"
}
],
"ascendant": {
"longitude": 132.18987983509504,
"sign": "Leo",
"degree": 12.189879835095041
},
"midheaven": {
"longitude": 31.41223081969011,
"sign": "Taurus",
"degree": 1.4122308196901088
},
"partOfFortune": {
"sign": "Leo",
"degree": 27.049918975242292,
"longitude": 147.0499189752423,
"sect": "day",
"house": 1
},
"vertex": {
"longitude": 269.09717021356005,
"sign": "Sagittarius",
"degree": 29.097170213560048,
"house": 5
}
},
"natalSunPosition": {
"longitude": 113.00452053215861,
"sign": "Cancer",
"degree": 23.004520532158608
},
"interpretation": {
"summary": "Solar Return chart for your 2026 birthday year. This chart is cast for the exact moment the Sun returns to its natal position, symbolizing a new solar year.",
"purpose": "Solar return charts are used for annual forecasting. The chart reveals themes, opportunities, and challenges for the year ahead from birthday to birthday. Focus on the Ascendant sign, angular planets, and aspects to natal positions.",
"keyThemes": [
"Annual themes and life direction",
"Career and public life developments",
"Relationships and partnerships",
"Personal growth and self-expression",
"Home and family matters"
]
}
}Response fields
| Field | Type | Description |
|---|---|---|
birthDaterequired | string | Original birth date used for natal Sun longitude calculation. |
solarReturnDaterequired | string | Exact solar return moment, when the transiting Sun conjuncts the natal Sun longitude. Adjusted to requested timezone. This is your astrological birthday for the year. |
solarReturnYearrequired | number | Year of this solar return chart. Covers the period from this birthday to the next. |
locationrequired | object | Location used for the solar return chart. The Ascendant and house cusps change based on where you are at your birthday, a key technique in relocated solar returns. |
location.latituderequired | number | Observer latitude used for Placidus house cusp and Ascendant calculation in the solar return chart. |
location.longituderequired | number | Observer longitude used for local sidereal time and Midheaven calculation in the solar return chart. |
location.timezonerequired | number | Timezone offset from UTC applied to output datetime formatting. |
chartrequired | object | Full natal-style chart erected for the solar return moment. Contains all 14 celestial bodies (10 classical planets, lunar nodes, Chiron, Black Moon Lilith), 12 house cusps, aspects, Ascendant, and Midheaven in the tropical zodiac. |
chart.birthDetailsrequired | object | Birth details used to generate this chart. |
chart.birthDetails.daterequired | string (date) | Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day. |
chart.birthDetails.timerequired | string (time) | Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown. |
chart.birthDetails.latituderequired | number | Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South. |
chart.birthDetails.longituderequired | number | Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West. |
chart.birthDetails.timezonerequired | number | Timezone offset from UTC in decimal hours, resolved for the birth date. Examples: New York = -5 in winter and -4 in summer, London = 0, India = 5.5, Tokyo = 9. |
Show all fieldsShow fewer fields
| Field | Type | Description |
|---|---|---|
chart.planetsrequired | array of object | All 14 celestial bodies in the tropical zodiac with house placements: the 10 classical planets (Sun through Pluto), the lunar nodes (North Node, South Node, in the requested `nodeType` convention), Chiron, and Black Moon Lilith. Chiron is included for charts from 1600 to 2500 and omitted outside that range. |
chart.planets[].namerequired | string enum | Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The lunar nodes follow the request nodeType, which defaults to the true (osculating) node; pass "mean" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected. |
chart.planets[].longituderequired | number | Apparent geocentric tropical longitude on the true ecliptic of date, in degrees (0-360): light time and aberration applied, nutation included, the convention desktop chart software and the NASA JPL Horizons observer tables print, so it compares directly with either. Primary coordinate for zodiac sign and aspect calculations. |
chart.planets[].latituderequired | number | Apparent geocentric ecliptic latitude of date, in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit). |
chart.planets[].signrequired | string | Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude. |
chart.planets[].degreerequired | number | Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign. |
chart.planets[].houserequired | integer | House placement (1-12). Determined by the selected house system and birth location. |
chart.planets[].speedrequired | number | Daily motion in degrees per day. Negative values indicate retrograde motion. |
chart.planets[].isRetrograderequired | boolean | Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection. |
chart.housesrequired | array of object | All 12 house cusps calculated using the selected house system. |
chart.houses[].numberrequired | integer | House number (1-12). Each house governs specific life themes in Western astrology. |
chart.houses[].longituderequired | number | Ecliptic longitude of this house cusp in degrees (0-360). |
chart.houses[].signrequired | string | Zodiac sign on this house cusp. Colors the themes of this life area. |
chart.houses[].degreerequired | number | Degree within the zodiac sign on this cusp (0-29.999). |
chart.houseSystemrequired | string enum | House system used for this chart (placidus, whole-sign, equal, or koch). |
chart.aspectsrequired | array of object | All planetary aspects found in this chart with orbs, strength, and applying/separating status. |
chart.aspects[].planet1required | string enum | First planet in the aspect pair. |
chart.aspects[].planet2required | string enum | Second planet in the aspect pair. |
chart.aspects[].typerequired | string enum | Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate. |
chart.aspects[].anglerequired | number | Exact angular separation that defines this aspect type in degrees. |
chart.aspects[].orbrequired | number | Deviation from exact aspect in degrees. Tighter orb means stronger influence. |
chart.aspects[].isApplyingrequired | boolean | Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger. |
chart.aspects[].strengthrequired | number | Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum. |
chart.aspects[].interpretationrequired | string enum | Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees. |
chart.partOfFortunerequired | object | Part of Fortune (Lot of Fortune). A point derived from the Ascendant and the two luminaries that marks an area of ease, vitality, and material wellbeing in the chart. |
chart.partOfFortune.signrequired | string | Zodiac sign holding the Part of Fortune. |
chart.partOfFortune.degreerequired | number | Degree within the Part of Fortune sign (0-29.999). |
chart.partOfFortune.longituderequired | number | Absolute ecliptic longitude of the Part of Fortune (0-360). |
chart.partOfFortune.houserequired | integer | House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign. |
chart.partOfFortune.sectrequired | string enum | Chart sect used for the calculation. Day (diurnal) when the Sun is above the horizon, night (nocturnal) when below. Day charts use Ascendant plus Moon minus Sun, night charts use Ascendant plus Sun minus Moon. |
chart.vertexrequired | object | Vertex. The western intersection of the prime vertical with the ecliptic, often read as a point of fated encounters and turning-point relationships. The opposite point is the Anti-Vertex. |
chart.vertex.signrequired | string | Zodiac sign holding the Vertex. |
chart.vertex.degreerequired | number | Degree within the Vertex sign (0-29.999). |
chart.vertex.longituderequired | number | Absolute ecliptic longitude of the Vertex (0-360). |
chart.vertex.houserequired | integer | House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign. |
natalSunPositionrequired | object | Original natal Sun position that the transiting Sun returns to. This conjunction defines the solar return moment. |
natalSunPosition.longituderequired | number | Natal Sun ecliptic longitude in degrees (0-360). The transiting Sun returns to this exact degree each year. |
natalSunPosition.signrequired | string | Tropical zodiac sign of the natal Sun (your Sun sign). |
natalSunPosition.degreerequired | number | Degree within the zodiac sign (0-29.999). The precise position the Sun returns to. |
interpretationrequired | object | Solar return interpretation with annual forecast themes. Solar returns are the primary technique in Western astrology for year-ahead predictions. |
interpretation.summaryrequired | string | Narrative overview of the solar return year themes and energy. |
interpretation.purposerequired | string | Explanation of how to use solar return charts for annual forecasting, identifying yearly themes, and timing predictions. |
interpretation.keyThemesrequired | array of string | Key life areas and themes highlighted by this solar return chart. Focus on these for the birthday year. |
Supported options
lang
entrdeeshiptfrruzh-Hanszh-Hant
houseSystem
placiduswhole-signequalkoch
Call it in your language.
Every snippet is generated from the live OpenAPI spec, so method names, parameters, and fields always match production.
import { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.astrology.generateSolarReturn({ body: { birthDate: '1990-07-15', birthTime: '14:30:00', returnYear: 2026, latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York' } })Install: npm install @roxyapi/sdk
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.astrology.generate_solar_return(birth_date='1990-07-15', birth_time='14:30:00', return_year=2026, latitude=40.7128, longitude=-74.006, timezone='America/New_York')Install: pip install roxy-sdk
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->astrology->generateSolarReturn(birthDate: '1990-07-15', birthTime: '14:30:00', returnYear: 2026, latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York');Install: composer require roxyapi/sdk
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Astrology.SolarReturn.PostAsync(new() { /* request fields above */ });Install: dotnet add package RoxyApi.Sdk
import roxyapi "github.com/RoxyAPI/sdk-go"
roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Astrology.GenerateSolarReturn(ctx, nil, roxyapi.GenerateSolarReturnJSONRequestBody{ /* request fields above */ })Install: go get github.com/RoxyAPI/sdk-go
use roxyapi::{Roxy, types};
async fn call(roxy: &Roxy, params: &types::GenerateSolarReturnParams, body: &types::GenerateSolarReturnRequest) -> Result<(), roxyapi::Error> {
let result = roxy.astrology().generate_solar_return(params, body).await?;
println!("{result:?}");
Ok(())
}Install: cargo add roxyapi
curl -X POST "https://roxyapi.com/api/v2/astrology/solar-return" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"birthDate":"1990-07-15","birthTime":"14:30:00","returnYear":2026,"latitude":40.7128,"longitude":-74.006,"timezone":"America/New_York"}'Prefer to try before you write code? Run this Western Astrology endpoint live in the API playground and inspect a real production response.
More Solar Return endpoints
The Solar Return API bundles these related endpoints under one key.
/astrology/lunar-returnLunar Return Chart - Monthly emotional forecast with Moon cycle chart
Generate a lunar return chart for any month, cast for the exact moment the transiting Moon returns to its natal ecliptic longitude. The Moon completes one sidereal orbit every ~27.3 days, making this the primary technique for monthly astrological forecasting. Returns full tropical zodiac chart with planetary positions, house cusps, aspects, Ascendant, and Midheaven. Reveals emotional patterns, domestic focus, and intuitive themes for the coming month. Lunar return chart API, monthly horoscope forecast, Moon cycle chart, emotional astrology prediction.
/astrology/planetary-returnsPlanetary Return Chart - Saturn return, Jupiter return, and inner planet cycles
Generate a planetary return chart for Mercury, Venus, Mars, Jupiter, or Saturn. A planetary return occurs when a transiting planet conjuncts its natal longitude, marking the beginning of a new cycle. Saturn return (~29 years) is the most significant life milestone in Western astrology. Jupiter return (~12 years) signals expansion and growth phases. Mars return (~2 years) resets energy and drive. Returns full tropical zodiac chart with all planetary positions, house cusps, and aspects. Planetary return chart API, Saturn return calculator, Jupiter return chart, Mars return forecast.
Remote MCP for AI agents
Every Western Astrology endpoint is a callable tool on the Remote MCP server over Streamable HTTP. No local setup, no Docker. Claude, ChatGPT, Cursor, and any MCP client auto-discover the tools and ground their answers in verified data.
claude mcp add --transport http \
roxy-astrology https://roxyapi.com/mcp/astrology \
--header "X-API-Key: YOUR_KEY"Tool name for POST /astrology/solar-return: post_astrology_solar_return. Full MCP setup guide
What you can build
- Launch natal chart apps with professional-grade accuracy: birth charts, planet positions, house placements, aspects, and element analysis ready for your UI
- Add zodiac compatibility scoring to dating apps: synastry analysis, composite charts, and compatibility scores with detailed relationship dynamics
- Ship personalized horoscope platforms: editorial daily, weekly, monthly, and yearly columns with unique content per sign, the dated events each one rests on returned beside the prose for fact-checking, active transit metadata, Moon phase data, and any past or future period on request for editorial pre-publishing
- Build AI astrology chatbots with MCP: your OpenAI, Claude, or Gemini agent auto-discovers and calls every astrology endpoint with zero integration code
- Power wellness and lifestyle apps with real-time transits, moon phase calendars, solar returns, and planetary movement alerts for self-discovery features
- Create astrology content engines: automated zodiac content with house-based uniqueness per sign, horoscope newsletters with real lunar event dates, transit alerts, and year-ahead pages built from every eclipse and every retrograde and direct station of the year with the house each one falls in for that sign
Related capabilities
Solar Return API FAQ
What does the Solar Return API return?
Generate a solar return chart for any year, the foundational technique for annual astrological forecasting. Every response is structured JSON with documented fields, not free text, so you map it straight into your product.
How do I authenticate with the Solar Return API?
Pass your key in the X-API-Key header on every request. Keys are delivered instantly at checkout with no approval queue. Use a secret sk key server side, or mint a publishable pk key locked to your origins for browser and no-code use.
Does the Solar Return API support multiple languages?
Yes. Append the lang query parameter to any endpoint for responses in English, German, Spanish, French, Hindi, Portuguese, Russian and Turkish. The translated payload includes the full interpretation text, not just field labels.
Do I need coordinates to call the Solar Return API?
No. Call GET location/search with a city name first, then pass latitude, longitude, and timezone from the first result into the request. Never ask users to type coordinates. Timezone accepts a decimal offset or an IANA name.
Is the Solar Return API available over Remote MCP for AI agents?
Yes. Every endpoint is exposed as a callable tool on the Remote MCP server at https://roxyapi.com/mcp/astrology over Streamable HTTP, so Claude, ChatGPT, Cursor, and any MCP client auto-discover it with no local setup or Docker.
How is the Solar Return API billed?
Flat pricing: 1 request equals 1 quota unit, REST and MCP identical, with no credit weighting or per-token markup. Every plan includes all 18+ domains, so the Solar Return API is included at no extra cost.
What houseSystem values does the Solar Return API accept?
The houseSystem parameter accepts placidus, whole-sign, equal, koch. Case-insensitive where it is a path value.
Start using Solar Return API today.
Birth charts checked cusp by cusp, and horoscopes that name the dated sky events behind each reading.
All 18+ domains included with every plan. Every endpoint, MCP server, SDK, and templates.
Plans from $39/mo, starting at $1.80 per domain on annual billing. No credit card required for testing.
View Pricing & Get API Key