Progressions Chart Image

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

Overview

Renders a secondary-progressions bi-wheel as a PNG image and returns a signed URL to it. The wheel shows the natal chart on the inner ring and the secondary-progressed chart on the outer ring, with cross-wheel aspects drawn from progressed planets to natal planets. The signed URL is valid for 24 hours and can be embedded in a UI or downloaded.

For the raw progressions data (progressed positions, angles, and progressed-to-natal aspects) without the rendered image, use forecasting/progressions.

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.
`second`	integer	No	Default 0.
`latitude`, `longitude`	number	Yes	Birth location (signed decimal degrees).
`timezone`	string	Yes	IANA timezone (e.g. `Asia/Kolkata`).
`progression_year`	integer	No	Target year for the progressed chart. Defaults to today (in birth timezone) if the three date fields are omitted.
`progression_month`	integer	No	Target month. Defaults to the current month.
`progression_day`	integer	No	Target day. Defaults to the current day.
`house_system`	string	No	Default `placidus`.
`node_type`	string	No	Default `true`.

Response shape

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

Field	Description
`chart_url`	Signed URL to the rendered PNG. Valid for 24 hours. Embed directly in `<img src>` or fetch as binary.
`expires_at`	Unix timestamp when the signed URL expires.
`target_date`	The progression target date used (`YYYY-MM-DD`) — requested date, or today if it defaulted.
`target_date_text`	Human-readable target date, e.g. `17 June 2026`.
`progression_date_source`	`provided` if the date was passed, or `current_date` if it defaulted to today.
`wheel_type`	Always `bi_wheel`.
`inner_ring`	Always `natal`.
`outer_ring`	Always `progressed_secondary`.

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/progressions-chart-image?key=<cacheKey>&expires=<unix>&token=<hmac>

Fetch it with a plain GET (no auth headers required). The response is an image/png. The wheel is a bi-wheel: the natal chart forms the inner ring and the secondary-progressed chart forms the outer ring.

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, progression target date, house system, node type). Identical requests return meta.cache: "HIT"; fresh computations show MISS.

Because the default progression date is today, a request with no date fields naturally produces a new cache entry each calendar day.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	Required birth field absent. The `progression_year/month/day` fields are optional (default to today).
400	`INVALID_DATE`	Invalid progression target date.
400	`INVALID_JSON`	Request body is not valid JSON.
403	`INVALID_SIGNATURE`	Signed URL token invalid or tampered with. Re-request via POST.
404	`CACHE_MISS`	GET for a chart whose data was never generated. Call POST first.
405	`METHOD_NOT_ALLOWED`	Only POST (create) and GET (fetch image) are supported.
410	`URL_EXPIRED`	Signed URL past its 24-hour expiry. Re-request via POST.
500	`EPHEM_ERROR`	Chart computation failed.
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/progressions-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",
        "node_type": "true",
        "progression_year": 2026,
        "progression_month": 6,
        "progression_day": 17
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/western/forecasting/progressions-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',
      node_type: 'true',
      progression_year: 2026,
      progression_month: 6,
      progression_day: 17
    })
  }
);
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/progressions-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',
        'node_type': 'true',
        'progression_year': 2026,
        'progression_month': 6,
        'progression_day': 17
    }
)
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',
    'node_type' => 'true',
    'progression_year' => 2026,
    'progression_month' => 6,
    'progression_day' => 17,
];

$ch = curl_init('https://starsapi.com/api/v3/western/forecasting/progressions-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/progressions-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',
      'node_type': 'true',
      'progression_year': 2026,
      'progression_month': 6,
      'progression_day': 17,
    }),
  );
  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/progressions-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",
            "node_type": "true",
            "progression_year": 2026,
            "progression_month": 6,
            "progression_day": 17
        }
        """.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",
        "node_type": "true",
        "progression_year": 2026,
        "progression_month": 6,
        "progression_day": 17
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/western/forecasting/progressions-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",
        "node_type": "true",
        "progression_year": 2026,
        "progression_month": 6,
        "progression_day": 17,
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/western/forecasting/progressions-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/progressions-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',
  'node_type' => 'true',
  'progression_year' => 2026,
  'progression_month' => 6,
  'progression_day' => 17
}

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_url": "https://starsapi.com/api/v3/western/forecasting/progressions-chart-image?key=7a7e4061b2a34f233b0f5cd04d1c99f7&expires=1784291453&token=7d75dd064c34b29a22a8845f97bbdc40",
    "expires_at": 1784291453,
    "target_date": "2026-06-17",
    "target_date_text": "17 June 2026",
    "progression_date_source": "provided",
    "wheel_type": "bi_wheel",
    "inner_ring": "natal",
    "outer_ring": "progressed_secondary"
  },
  "meta": {
    "endpoint": "/api/v3/western/forecasting/progressions-chart-image",
    "version": "3.0",
    "house_system": "placidus",
    "cache": "MISS",
    "response_time_ms": 9
  }
}