Synastry Chart

Endpoint POST https://starsapi.com/api/v3/western/compatibility/synastry-chart

Computes both natal charts plus synastry inter-aspects and returns a signed URL to a bi-wheel PNG image showing Person A’s chart on the inner ring and Person B’s planets on the outer ring. The URL is valid for 24 hours.

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

Two person objects are required. Each contains birth data:

Field	Type	Required	Description
`person1`	object	Yes	Inner-ring person (see fields below).
`person2`	object	Yes	Outer-ring person (same fields).
`house_system`	string	No	Default `placidus`.
`node_type`	string	No	`true` (default) or `mean`.
`center_text`	string	No	Custom text in chart center.

Person object fields

Field	Type	Required	Description
`name`	string	No	Label on chart. Default `"Person A"` / `"Person B"`.
`year`	integer	Yes	Birth year.
`month`	integer	Yes	Birth month, 1–12.
`day`	integer	Yes	Day of month.
`hour`	integer	Yes	Hour, 0–23.
`minute`	integer	Yes	Minute, 0–59.
`second`	integer	No	Default `0`.
`latitude`	number	Yes	Decimal degrees.
`longitude`	number	Yes	Decimal degrees.
`timezone`	string	Yes	IANA timezone identifier.

Response shape

Field	Type	Description
`chart_url`	string	Signed URL to the bi-wheel PNG image. Valid for 24 hours.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	`person1` or `person2` missing, or required sub-fields absent.
405	`METHOD_NOT_ALLOWED`	Non-POST request.
500	`EPHEMERIS_ERROR`	Chart computation failed for one of the persons.

Notes

The image URL is a signed, time-limited link — cache the URL or download the image within 24 hours.
For synastry data (inter-aspects, planet positions) without the chart image, use Synastry.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/western/compatibility/synastry-chart" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "person1": {
            "name": "Person A",
            "year": 1990,
            "month": 5,
            "day": 20,
            "hour": 14,
            "minute": 30,
            "second": 0,
            "latitude": 28.6139,
            "longitude": 77.209,
            "timezone": "Asia/Kolkata"
        },
        "person2": {
            "name": "Person B",
            "year": 1992,
            "month": 8,
            "day": 10,
            "hour": 10,
            "minute": 15,
            "second": 0,
            "latitude": 19.076,
            "longitude": 72.8777,
            "timezone": "Asia/Kolkata"
        }
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/western/compatibility/synastry-chart',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      person1: 'Array',
      person2: 'Array'
    })
  }
);
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/compatibility/synastry-chart',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    json={
        'person1': 'Array',
        'person2': 'Array'
    }
)
result = response.json()

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

<?php
$payload = [
    'person1' => 'Array',
    'person2' => 'Array',
];

$ch = curl_init('https://starsapi.com/api/v3/western/compatibility/synastry-chart');
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/compatibility/synastry-chart'),
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'person1': 'Array',
      'person2': 'Array',
    }),
  );
  return jsonDecode(response.body);
}

import Foundation

func getAscendant() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/western/compatibility/synastry-chart"
    )!)
    request.httpMethod = "POST"
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = """
        {
            "person1": {
                "name": "Person A",
                "year": 1990,
                "month": 5,
                "day": 20,
                "hour": 14,
                "minute": 30,
                "second": 0,
                "latitude": 28.6139,
                "longitude": 77.209,
                "timezone": "Asia/Kolkata"
            },
            "person2": {
                "name": "Person B",
                "year": 1992,
                "month": 8,
                "day": 10,
                "hour": 10,
                "minute": 15,
                "second": 0,
                "latitude": 19.076,
                "longitude": 72.8777,
                "timezone": "Asia/Kolkata"
            }
        }
        """.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 = """
    {
        "person1": {
            "name": "Person A",
            "year": 1990,
            "month": 5,
            "day": 20,
            "hour": 14,
            "minute": 30,
            "second": 0,
            "latitude": 28.6139,
            "longitude": 77.209,
            "timezone": "Asia/Kolkata"
        },
        "person2": {
            "name": "Person B",
            "year": 1992,
            "month": 8,
            "day": 10,
            "hour": 10,
            "minute": 15,
            "second": 0,
            "latitude": 19.076,
            "longitude": 72.8777,
            "timezone": "Asia/Kolkata"
        }
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/western/compatibility/synastry-chart")
        .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{}{
        "person1": "Array",
        "person2": "Array",
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/western/compatibility/synastry-chart",
        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/compatibility/synastry-chart')
payload = {
  'person1' => 'Array',
  'person2' => 'Array'
}

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/compatibility/synastry-chart-image?key=a1b2c3…&expires=1719100000&token=f4e5d6…"
  },
  "meta": {
    "endpoint": "/api/v3/western/compatibility/synastry-chart",
    "version": "3.0",
    "response_time_ms": 45,
    "timestamp": "2026-06-22T10:00:00+05:30",
    "credits_remaining": 196400,
    "request_id": "abc123def456"
  }
}