Solar Return

Endpoint POST https://starsapi.com/api/v3/western/predictions/solar-return

Calculates the Solar Return chart — the exact moment the transiting Sun returns to its natal position for a given year — and returns prewritten predictions for the SR Ascendant sign and each of the 10 planets’ house placements. A complete “year ahead” reading from a single API call.

What is a Solar Return? — the chart cast for the precise moment the Sun returns to its birth position each year (near the birthday). It describes the themes, challenges, and opportunities for the year ahead. Professional astrologers consider it the single most important predictive chart.

Authentication

Method	Example
Header (recommended)	`X-Api-Key: am_live_xxxxxxxxxxxx`
Bearer	`Authorization: Bearer am_live_xxxxxxxxxxxx`
Query	`?api_key=am_live_xxxxxxxxxxxx`

Request body

Field	Type	Required	Description
Natal birth data
`year`	integer	Yes	Birth year (1800–2400).
`month`	integer	Yes	Birth month, 1–12.
`day`	integer	Yes	Birth day.
`hour`	integer	Yes	Birth hour, 0–23.
`minute`	integer	Yes	Birth minute, 0–59.
`second`	integer	No	Default 0.
`latitude`	number	Yes	Natal birth latitude, decimal degrees.
`longitude`	number	Yes	Natal birth longitude, decimal degrees.
`timezone`	string	Yes	IANA timezone of birth.
Solar Return parameters
`return_year`	integer	Yes	The year to calculate the Solar Return for (e.g. 2026).
`return_latitude`	number	No	Location for the SR chart. Defaults to birth latitude.
`return_longitude`	number	No	Location for the SR chart. Defaults to birth longitude.
Options
`language`	string	No	Default `en`.
`house_system`	string	No	Default `placidus`.

Response shape

Field	Type	Description
`return_year`	integer	The requested Solar Return year.
`solar_return_date`	string	Exact SR moment in UTC (Y-m-d H:i:s).
`ascendant`	object	SR Ascendant `sign`, `degree`, and `prediction`.
`planets[]`	array	10 entries (Sun…Pluto), each with:
`.planet`	string	Planet name.
`.sign`	string	Sign the planet occupies in the SR chart.
`.house`	integer	House (1–12) in the SR chart.
`.retrograde`	boolean	Whether the planet is retrograde at the SR moment.
`.prediction`	object	`title`, `text`, `keywords`.

Return location

The Solar Return chart can be cast for the person’s current location rather than their birth location. Many astrologers recommend using the city where the person will be on or near their birthday. Pass return_latitude and return_longitude to override the birth coordinates. If omitted, the birth location is used.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	Required field absent.
400	`INVALID_DATE`	Bad calendar date or return_year out of range.
400	`INVALID_TIMEZONE`	Non-IANA timezone.
400	`INVALID_COORDINATE`	Lat/lon out of range.
405	`METHOD_NOT_ALLOWED`	Non-POST request.
500	`COMPUTE_ERROR`	Chart computation or SR moment calculation failed.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/western/predictions/solar-return" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "return_year": 2026,
        "return_latitude": 19.076,
        "return_longitude": 72.8777,
        "language": "en",
        "house_system": "placidus"
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/western/predictions/solar-return',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      year: 1990,
      month: 5,
      day: 20,
      hour: 14,
      minute: 30,
      second: 0,
      latitude: 28.6139,
      longitude: 77.209,
      timezone: 'Asia/Kolkata',
      return_year: 2026,
      return_latitude: 19.076,
      return_longitude: 72.8777,
      language: 'en',
      house_system: 'placidus'
    })
  }
);
const result = await response.json();

if (result.success) {
  console.log(result.data);
}

import requests
import os

response = requests.post(
    'https://starsapi.com/api/v3/western/predictions/solar-return',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    json={
        'year': 1990,
        'month': 5,
        'day': 20,
        'hour': 14,
        'minute': 30,
        'second': 0,
        'latitude': 28.6139,
        'longitude': 77.209,
        'timezone': 'Asia/Kolkata',
        'return_year': 2026,
        'return_latitude': 19.076,
        'return_longitude': 72.8777,
        'language': 'en',
        'house_system': 'placidus'
    }
)
result = response.json()

if result['success']:
    print(result['data'])

<?php
$payload = [
    'year' => 1990,
    'month' => 5,
    'day' => 20,
    'hour' => 14,
    'minute' => 30,
    'second' => 0,
    'latitude' => 28.6139,
    'longitude' => 77.209,
    'timezone' => 'Asia/Kolkata',
    'return_year' => 2026,
    'return_latitude' => 19.076,
    'return_longitude' => 72.8777,
    'language' => 'en',
    'house_system' => 'placidus',
];

$ch = curl_init('https://starsapi.com/api/v3/western/predictions/solar-return');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . getenv('STARSAPI_KEY'),
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success']) {
    print_r($data['data']);
}

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<Map<String, dynamic>> getAscendant() async {
  final response = await http.post(
    Uri.parse('https://starsapi.com/api/v3/western/predictions/solar-return'),
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'year': 1990,
      'month': 5,
      'day': 20,
      'hour': 14,
      'minute': 30,
      'second': 0,
      'latitude': 28.6139,
      'longitude': 77.209,
      'timezone': 'Asia/Kolkata',
      'return_year': 2026,
      'return_latitude': 19.076,
      'return_longitude': 72.8777,
      'language': 'en',
      'house_system': 'placidus',
    }),
  );
  return jsonDecode(response.body);
}

import Foundation

func getAscendant() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/western/predictions/solar-return"
    )!)
    request.httpMethod = "POST"
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = """
        {
            "year": 1990,
            "month": 5,
            "day": 20,
            "hour": 14,
            "minute": 30,
            "second": 0,
            "latitude": 28.6139,
            "longitude": 77.209,
            "timezone": "Asia/Kolkata",
            "return_year": 2026,
            "return_latitude": 19.076,
            "return_longitude": 72.8777,
            "language": "en",
            "house_system": "placidus"
        }
        """.data(using: .utf8)

    let (data, _) = try await URLSession.shared.data(for: request)
    return try JSONSerialization.jsonObject(with: data) as! [String: Any]
}

import okhttp3.*
import org.json.JSONObject

val client = OkHttpClient()
val JSON = "application/json; charset=utf-8".toMediaType()

fun getAscendant(callback: (JSONObject) -> Unit) {
    val payload = """
    {
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "return_year": 2026,
        "return_latitude": 19.076,
        "return_longitude": 72.8777,
        "language": "en",
        "house_system": "placidus"
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/western/predictions/solar-return")
        .addHeader("X-Api-Key", "YOUR_API_KEY")
        .post(payload.toRequestBody(JSON))
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onResponse(call: Call, response: Response) {
            callback(JSONObject(response.body!!.string()))
        }
        override fun onFailure(call: Call, e: java.io.IOException) {
            e.printStackTrace()
        }
    })
}

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    payload, _ := json.Marshal(map[string]interface{}{
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "return_year": 2026,
        "return_latitude": 19.076,
        "return_longitude": 72.8777,
        "language": "en",
        "house_system": "placidus",
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/western/predictions/solar-return",
        bytes.NewBuffer(payload))
    req.Header.Set("X-Api-Key", os.Getenv("STARSAPI_KEY"))
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result["data"])
}

require 'net/http'
require 'json'

uri = URI('https://starsapi.com/api/v3/western/predictions/solar-return')
payload = {
  'year' => 1990,
  'month' => 5,
  'day' => 20,
  'hour' => 14,
  'minute' => 30,
  'second' => 0,
  'latitude' => 28.6139,
  'longitude' => 77.209,
  'timezone' => 'Asia/Kolkata',
  'return_year' => 2026,
  'return_latitude' => 19.076,
  'return_longitude' => 72.8777,
  'language' => 'en',
  'house_system' => 'placidus'
}

req = Net::HTTP::Post.new(uri)
req['X-Api-Key'] = ENV['STARSAPI_KEY']
req['Content-Type'] = 'application/json'
req.body = payload.to_json

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
res = http.request(req)

data = JSON.parse(res.body)
puts data['data'] if data['success']

200 RESPONSE

{
  "status": 200,
  "success": true,
  "data": {
    "language": "en",
    "return_year": 2026,
    "solar_return_date": "2026-05-20 02:00:50",
    "house_system": "placidus",
    "ascendant": {
      "sign": "Gemini",
      "degree": 4.2381,
      "prediction": {
        "title": "Solar Return Ascendant in Gemini",
        "text": "Communication, curiosity, and social connection define your year ahead…",
        "keywords": ["Mental acceleration", "Conversations matter", "Stay curious"]
      }
    },
    "planets": [
      {
        "planet": "Sun",
        "sign": "Taurus",
        "house": 12,
        "retrograde": false,
        "prediction": {
          "title": "Solar Return Sun in the 12th House",
          "text": "Solitude, spiritual development, and the completion of old cycles…",
          "keywords": ["Inner year", "Retreat is strategic", "Preparing for rebirth"]
        }
      }
    ]
  },
  "meta": { "endpoint": "/api/v3/western/predictions/solar-return", "version": "3.0" }
}