Solar Return Chart Image

Endpoint POST https://starsapi.com/api/v3/western/forecasting/solar-return-chart-image

Overview

Renders a solar return chart wheel as a 1100×1100 PNG image. Computes the exact SR moment (Sun returning to natal longitude in the requested year), calculates all positions and aspects, and returns a signed URL to the rendered chart. The signed URL is valid for 24 hours and can be embedded in a UI or downloaded.

For the raw SR data (positions, houses, aspects, angles) without the rendered image, use forecasting/solar-return. For SR with text interpretations, use predictions/solar-return.

Authentication

Method	Example
Header (recommended)	`X-Api-Key: sa_live_xxxxxxxxxxxx`
Bearer	`Authorization: Bearer sa_live_xxxxxxxxxxxx`

Auth is required only for the POST request. The returned chart_url is pre-signed with HMAC and does not require an API key when fetched.

Request body

Field	Type	Required	Description
`year` – `minute`	integer	Yes	Standard birth data fields.
`latitude`, `longitude`	number	Yes	Birth location (signed decimal degrees).
`timezone`	string	Yes	IANA timezone (e.g. `Asia/Kolkata`).
`return_year`	integer	Yes	Year to calculate the solar return for. Range: 1800–2400.
`house_system`	string	No	Default `placidus`. Supports `koch`, `whole_sign`, `equal`, and 19 more.
`return_latitude`	number	No	Relocation latitude. Default: birth latitude.
`return_longitude`	number	No	Relocation longitude. Default: birth longitude.
`return_timezone`	string	No	Relocation IANA timezone. Default: birth timezone.
`name`	string	No	Native's name (used in chart footer if branding is enabled).
`center_text`	string	No	Text rendered in the center of the wheel. Default: `SR {year}`.
`branding`	object	No	Optional footer branding: `{ "name": "...", "url": "..." }`.

Relocation

Solar return charts are highly location-sensitive — the house cusps and rendered wheel change based on where the native is at the moment of the return. Pass return_latitude, return_longitude, and return_timezone to render the SR wheel for a different location (e.g. the native has relocated).

The return_location block in the response echoes back the coordinates and timezone actually used.

Response shape

The response envelope follows the standard v3 shape (status, success, data, meta). The data.chart object contains:

Field	Description
`code`	Chart code: `SR`.
`name`	Display name (e.g. `Solar Return 2026`).
`significance`	Short human-readable description of what this chart represents.
`return_year`	Year requested.
`solar_return_moment`	Exact UTC timestamp, datetime, and Julian day of the solar return.
`return_location`	Location used for the SR chart (birth or relocation).
`ascendant`	SR ascendant with longitude, sign, degree, and DMS string.
`chart_url`	Signed URL to the rendered PNG. Valid for 24 hours. Embed directly in `<img src>` or fetch as binary.

meta.house_system confirms the system used and meta.cache indicates cache HIT or MISS.

Fetching the image

The chart_url is a pre-signed URL of the form:

https://starsapi.com/api/v3/western/forecasting/solar-return-chart-image?key=<cacheKey>&expires=<unix>&token=<hmac>

Fetch it with a plain GET (no auth headers required). The response is an image/png with dimensions 1100×1100. Typical size: 250–280 KB.

Since the URL is signed with an expiry, do not store it long-term. Store the birth details and re-request the endpoint when you need the image again — the response will be a fast cache HIT if the same inputs were used recently.

Caching

Chart images are cached on disk for 24 hours, keyed by the full input set (birth data, return year, return location, house system). Identical requests return meta.cache: "HIT" with response times of ~3–5 ms; fresh computations show MISS with ~50–70 ms compute time.

Coordinates are rounded to 4 decimal places before hashing to avoid cache misses from floating-point drift (e.g. 77.2090 vs 77.209 hit the same cache entry).

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	Required field absent (including `return_year`).
400	`INVALID_RETURN_YEAR`	`return_year` outside 1800–2400.
400	`INVALID_TIMEZONE`	`return_timezone` is not a valid IANA identifier.
400	`INVALID_COORDINATES`	`return_latitude` or `return_longitude` out of range.
401	`INVALID_SIGNATURE`	Signed URL token invalid or tampered with. Re-request via POST.
410	`URL_EXPIRED`	Signed URL past its 24-hour expiry. Re-request via POST.
500	`COMPUTE_ERROR`	Solar return moment not found.
500	`RENDER_ERROR`	Wheel rendering failed.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/western/forecasting/solar-return-chart-image" \
  -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",
        "house_system": "placidus",
        "return_year": 2026
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/western/forecasting/solar-return-chart-image',
  {
    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',
      house_system: 'placidus',
      return_year: 2026
    })
  }
);
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/forecasting/solar-return-chart-image',
    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',
        'house_system': 'placidus',
        'return_year': 2026
    }
)
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',
    'house_system' => 'placidus',
    'return_year' => 2026,
];

$ch = curl_init('https://starsapi.com/api/v3/western/forecasting/solar-return-chart-image');
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/forecasting/solar-return-chart-image'),
    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',
      'house_system': 'placidus',
      'return_year': 2026,
    }),
  );
  return jsonDecode(response.body);
}

import Foundation

func getAscendant() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/western/forecasting/solar-return-chart-image"
    )!)
    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",
            "house_system": "placidus",
            "return_year": 2026
        }
        """.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",
        "house_system": "placidus",
        "return_year": 2026
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/western/forecasting/solar-return-chart-image")
        .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",
        "house_system": "placidus",
        "return_year": 2026,
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/western/forecasting/solar-return-chart-image",
        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/forecasting/solar-return-chart-image')
payload = {
  'year' => 1990,
  'month' => 5,
  'day' => 20,
  'hour' => 14,
  'minute' => 30,
  'second' => 0,
  'latitude' => 28.6139,
  'longitude' => 77.209,
  'timezone' => 'Asia/Kolkata',
  'house_system' => 'placidus',
  'return_year' => 2026
}

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": {
    "chart": {
      "code": "SR",
      "name": "Solar Return 2026",
      "significance": "The chart cast for the moment the transiting Sun returns to its natal position. Governs themes for the year ahead.",
      "return_year": 2026,
      "solar_return_moment": {
        "timestamp": 1779473820,
        "utc_datetime": "2026-05-20 08:37:00 UTC",
        "julian_day": 2461180.859
      },
      "return_location": {
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "label": "Birth location"
      },
      "ascendant": {
        "longitude": 102.5,
        "sign": "Cancer",
        "degree": 12,
        "dms": "12\u00b030'"
      },
      "chart_url": "https://starsapi.com/api/v3/western/forecasting/solar-return-chart-image?key=a3f8e2d1c9b4&expires=1720598400&token=e7a2b8c4d1f9e6a3b8c4d1f9e6a3b8c4d1f9e6a3b8c4d1f9e6a3b8c4d1f9e6a3"
    }
  },
  "meta": {
    "endpoint": "/api/v3/western/forecasting/solar-return-chart-image",
    "version": "3.0",
    "house_system": "placidus",
    "cache": "MISS",
    "response_time_ms": 59
  }
}