Synastry

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

Overview

Computes full synastry analysis between two natal charts. Returns inter-chart aspects (Person 1’s planets aspecting Person 2’s planets), key highlighted aspects, aspect groupings (harmonious/challenging), a compatibility score, and house overlays in both directions (Person 1’s planets in Person 2’s houses and vice versa).

This is the raw calculation version. For synastry with prewritten text interpretations, use predictions/synastry-aspects and predictions/synastry-houses.

Authentication

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

Request body

Uses nested person1/person2 objects, each containing standard birth data:

Field	Type	Required	Description
`person1.year` – `person1.minute`		Yes	Person 1 birth data.
`person1.latitude`, `person1.longitude`	number	Yes	Person 1 birth location.
`person1.timezone`	string	Yes	Person 1 IANA timezone.
`person2.*`		Yes	Same fields for Person 2.
`house_system`	string	No	Default `placidus`. Applied to both charts.
`node_type`	string	No	Default `true`.
`include_minor_aspects`	boolean	No	Include minor aspects. Default `false`.

Response shape

Field	Description
`person1_planets`	Person 1 natal positions.
`person2_planets`	Person 2 natal positions.
`synastry_aspects.inter_aspects`	All cross-chart aspects with planets, signs, degrees, orbs.
`synastry_aspects.key_aspects`	Highlighted important aspects.
`synastry_aspects.aspect_groups`	Grouped by harmonious/challenging.
`synastry_aspects.compatibility`	Compatibility scoring.
`synastry_aspects.house_overlays`	House overlays with synastry meanings per house.
`house_overlays`	`a_in_b_houses` + `b_in_a_houses` — which planets land in which houses.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	Required field absent in person1 or person2.
400	`INVALID_DATE`	Invalid date in either person.
500	`EPHEMERIS_ERROR`	Computation failed.

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

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

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

<?php
$payload = [
    'person1' => 'Array',
    'person2' => 'Array',
    'house_system' => 'placidus',
    'node_type' => 'true',
    'include_minor_aspects' => false,
];

$ch = curl_init('https://starsapi.com/api/v3/western/compatibility/synastry');
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'),
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'person1': 'Array',
      'person2': 'Array',
      'house_system': 'placidus',
      'node_type': 'true',
      'include_minor_aspects': false,
    }),
  );
  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"
    )!)
    request.httpMethod = "POST"
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = """
        {
            "person1": {
                "year": 1990,
                "month": 5,
                "day": 20,
                "hour": 14,
                "minute": 30,
                "second": 0,
                "latitude": 28.6139,
                "longitude": 77.209,
                "timezone": "Asia/Kolkata"
            },
            "person2": {
                "year": 1992,
                "month": 8,
                "day": 15,
                "hour": 10,
                "minute": 0,
                "second": 0,
                "latitude": 19.076,
                "longitude": 72.8777,
                "timezone": "Asia/Kolkata"
            },
            "house_system": "placidus",
            "node_type": "true",
            "include_minor_aspects": false
        }
        """.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": {
            "year": 1990,
            "month": 5,
            "day": 20,
            "hour": 14,
            "minute": 30,
            "second": 0,
            "latitude": 28.6139,
            "longitude": 77.209,
            "timezone": "Asia/Kolkata"
        },
        "person2": {
            "year": 1992,
            "month": 8,
            "day": 15,
            "hour": 10,
            "minute": 0,
            "second": 0,
            "latitude": 19.076,
            "longitude": 72.8777,
            "timezone": "Asia/Kolkata"
        },
        "house_system": "placidus",
        "node_type": "true",
        "include_minor_aspects": false
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/western/compatibility/synastry")
        .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",
        "house_system": "placidus",
        "node_type": "true",
        "include_minor_aspects": false,
    })

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

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": {
    "person1_planets": { "Sun": { "longitude": 59.09, "sign": "Taurus" } },
    "person2_planets": { "Sun": { "longitude": 142.76, "sign": "Leo" } },
    "synastry_aspects": {
      "inter_aspects": [
        {
          "person_a_planet": "Sun",
          "person_a_sign": "Taurus",
          "person_a_degree": "29°05'34\"",
          "person_b_planet": "Saturn",
          "person_b_sign": "Aquarius",
          "aspect": "Square",
          "aspect_key": "square",
          "orb": 2.14,
          "is_applying": false
        }
      ],
      "key_aspects": [ "..." ],
      "aspect_groups": { "harmonious": [...], "challenging": [...] },
      "compatibility": { "score": 72, "..." : "..." },
      "house_overlays": {
        "a_in_b_houses": { "houses": { "1": { "house_sign": "Libra", "planets": ["Venus"] } } },
        "b_in_a_houses": { "houses": { "1": { "house_sign": "Virgo", "planets": [] } } }
      }
    },
    "house_overlays": {
      "a_in_b_houses": { "..." : "..." },
      "b_in_a_houses": { "..." : "..." }
    }
  },
  "meta": { "endpoint": "/api/v3/western/compatibility/synastry", "version": "3.0" }
}