Quick Start Playground SDK MCP Setup Free Templates AGENTS.md

Solar Return API

Annual birthday forecast with relocated chart

POST/astrology/solar-returnPOST/astrology/lunar-returnPOST/astrology/planetary-returns

Get API Key Try it live

Remote MCP server OpenAPI schema

Rated 4.5 by 127 developers

Includedwith every plan(at no extra cost)

Vedic Numerology Tarot Human Design Forecast Biorhythm I-Ching Crystals Dreams Angel Numbers Location

828 gold-standard tests, NASA JPL verified

12 domains, 1 API key

llms.txt for AI agents

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.

1 Resolve the location

GET

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

2 Call the Solar Return endpoint

POST /astrology/solar-return

# feed latitude, longitude and timezone from step 1
POST https://roxyapi.com/api/v2/astrology/solar-return

Request

POST /api/v2/astrology/solar-return

Parameters

Parameter	Type	Description
langquery	string enum	Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English. Default `en`.

Request body

Field	Type	Description
birthDate*	string (date)	Original birth date in YYYY-MM-DD format. Used to determine natal Sun longitude for the solar return calculation.
birthTime*	string (time)	Original birth time in 24-hour HH:MM:SS format. Determines exact natal Sun position for annual return timing.
returnYear*	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.
latitude*	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.
longitude*	number	Longitude of the solar return location in decimal degrees (-180 to 180). Affects house cusps and Ascendant of the return chart.
timezone*	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.
houseSystem	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

POST /astrology/solar-return

{
  "birthDate": "1990-07-15",
  "birthTime": "14:30:00",
  "returnYear": 2026,
  "latitude": 40.7128,
  "longitude": -74.006,
  "timezone": -5
}

Response

Structured JSON with documented fields, verified against NASA JPL Horizons across 828 gold-standard tests. Not hallucinated text.

200 OK

{
  "birthDate": "1990-07-15",
  "solarReturnDate": "2026-07-15T08:42:00",
  "solarReturnYear": 2026,
  "location": {
    "latitude": 0,
    "longitude": 0,
    "timezone": 0
  },
  "chart": {
    "birthDetails": {
      "date": "1990-07-15",
      "time": "14:30:00",
      "latitude": 40.7128,
      "longitude": -74.006,
      "timezone": -5
    },
    "planets": [
      {
        "name": "Sun",
        "longitude": 112.45,
        "latitude": 0.01,
        "sign": "Cancer",
        "degree": 22.45,
        "house": 7,
        "speed": 0.9571,
        "isRetrograde": false
      }
    ],
    "houses": [
      {
        "number": 1,
        "longitude": 45.32,
        "sign": "Taurus",
        "degree": 15.32
      }
    ],
    "houseSystem": "placidus",
    "aspects": [
      {
        "planet1": "Sun",
        "planet2": "Moon",
        "type": "TRINE",
        "angle": 120,
        "orb": 2.5,
        "isApplying": true,
        "strength": 75,
        "interpretation": "harmonious"
      }
    ],
    "partOfFortune": {
      "sign": "Aries",
      "degree": 27.24,
      "longitude": 27.24,
      "sect": "night"
    },
    "vertex": {
      "sign": "Virgo",
      "degree": 12.9,
      "longitude": 162.9
    }
  },
  "natalSunPosition": {
    "longitude": 0,
    "sign": "Cancer",
    "degree": 22.45
  },
  "interpretation": {
    "summary": "string",
    "purpose": "string",
    "keyThemes": [
      "string"
    ]
  }
}

Response fields

Field	Type	Description
birthDate*	string	Original birth date used for natal Sun longitude calculation.
solarReturnDate*	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.
solarReturnYear*	number	Year of this solar return chart. Covers the period from this birthday to the next.
location*	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.latitude*	number	Observer latitude used for Placidus house cusp and Ascendant calculation in the solar return chart.
location.longitude*	number	Observer longitude used for local sidereal time and Midheaven calculation in the solar return chart.
location.timezone*	number	Timezone offset from UTC applied to output datetime formatting.
chart*	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.birthDetails*	object	Birth details used to generate this chart.
chart.birthDetails.date*	string (date)	Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day.
chart.birthDetails.time*	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.latitude*	number	Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South.
chart.birthDetails.longitude*	number	Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West.
chart.birthDetails.timezone*	number	Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9.

Show all fields

Field	Type	Description
chart.planets*	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), Chiron, and Black Moon Lilith.
chart.planets[].name*	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).
chart.planets[].longitude*	number	Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations.
chart.planets[].latitude*	number	Ecliptic latitude 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[].sign*	string	Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude.
chart.planets[].degree*	number	Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign.
chart.planets[].house*	integer	House placement (1-12). Determined by the selected house system and birth location.
chart.planets[].speed*	number	Daily motion in degrees per day. Negative values indicate retrograde motion.
chart.planets[].isRetrograde*	boolean	Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection.
chart.houses*	array of object	All 12 house cusps calculated using the selected house system.
chart.houses[].number*	integer	House number (1-12). Each house governs specific life themes in Western astrology.
chart.houses[].longitude*	number	Ecliptic longitude of this house cusp in degrees (0-360).
chart.houses[].sign*	string	Zodiac sign on this house cusp. Colors the themes of this life area.
chart.houses[].degree*	number	Degree within the zodiac sign on this cusp (0-29.999).
chart.houseSystem*	string enum	House system used for this chart (placidus, whole-sign, equal, or koch).
chart.aspects*	array of object	All planetary aspects found in this chart with orbs, strength, and applying/separating status.
chart.aspects[].planet1*	string enum	First planet in the aspect pair.
chart.aspects[].planet2*	string enum	Second planet in the aspect pair.
chart.aspects[].type*	string enum	Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate.
chart.aspects[].angle*	number	Exact angular separation that defines this aspect type in degrees.
chart.aspects[].orb*	number	Deviation from exact aspect in degrees. Tighter orb means stronger influence.
chart.aspects[].isApplying*	boolean	Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger.
chart.aspects[].strength*	number	Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum.
chart.aspects[].interpretation*	string enum	Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies.
chart.partOfFortune*	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.sign*	string	Zodiac sign holding the Part of Fortune.
chart.partOfFortune.degree*	number	Degree within the Part of Fortune sign (0-29.999).
chart.partOfFortune.longitude*	number	Absolute ecliptic longitude of the Part of Fortune (0-360).
chart.partOfFortune.sect*	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.vertex*	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.sign*	string	Zodiac sign holding the Vertex.
chart.vertex.degree*	number	Degree within the Vertex sign (0-29.999).
chart.vertex.longitude*	number	Absolute ecliptic longitude of the Vertex (0-360).
natalSunPosition*	object	Original natal Sun position that the transiting Sun returns to. This conjunction defines the solar return moment.
natalSunPosition.longitude*	number	Natal Sun ecliptic longitude in degrees (0-360). The transiting Sun returns to this exact degree each year.
natalSunPosition.sign*	string	Tropical zodiac sign of the natal Sun (your Sun sign).
natalSunPosition.degree*	number	Degree within the zodiac sign (0-29.999). The precise position the Sun returns to.
interpretation*	object	Solar return interpretation with annual forecast themes. Solar returns are the primary technique in Western astrology for year-ahead predictions.
interpretation.summary*	string	Narrative overview of the solar return year themes and energy.
interpretation.purpose*	string	Explanation of how to use solar return charts for annual forecasting, identifying yearly themes, and timing predictions.
interpretation.keyThemes*	array of string	Key life areas and themes highlighted by this solar return chart. Focus on these for the birthday year.

Supported options

lang

entrdeeshiptfrru

houseSystem

placiduswhole-signequalkoch

Call it in your language in seconds.

Every snippet is generated from the live OpenAPI spec, so method names, parameters, and fields always match production.

TypeScript

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: -5 } })

Install: npm install @roxyapi/sdk

Python

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

PHP

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: -5);

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

cURL

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":-5}'

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.

POST/astrology/lunar-return

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

Try it live

POST/astrology/planetary-returns

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

Try it live

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 Code / Cursor

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 in days

Add zodiac compatibility scoring to dating apps: synastry analysis, composite charts, and compatibility scores with detailed relationship dynamics

Ship personalized horoscope platforms: publisher-grade daily, weekly, and monthly forecasts with unique content per sign, active transit metadata, Moon phase data, and date scheduling 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 seasonal forecasts at scale

Related capabilities

Astrology Transits API

All of Western Astrology API

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 12 domains, so the Solar Return API is included at no extra cost.

What lang values does the Solar Return API accept?

The lang parameter accepts en, tr, de, es, hi, pt, fr, ru. Case-insensitive where it is a path value.

Start using Solar Return API today.

Ship your astrology app this weekend. Not this quarter.

All 12 domains included with every plan. Every endpoint, MCP server, SDK, and starters.

Plans from $39/mo, starting at $2.70 per domain on annual billing. No credit card required for testing.

View Pricing & Get API Key