Hemisphere Balance

Endpoint POST https://starsapi.com/api/v3/western/natal/hemisphere-balance

Overview

Analyzes planet distribution across hemispheres and quadrants. Where planets cluster in the chart reveals the native’s orientation: Eastern emphasis = self-reliant, Western = relationship-oriented, Northern = private/introspective, Southern = public/career-focused.

Also returns quadrant analysis (four groups of three houses each) and the dominant quadrant. House-system-dependent — changing the house system can shift planets between quadrants.

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
`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	Decimal degrees.
`longitude`	number	Yes	Decimal degrees.
`timezone`	string	Yes	IANA timezone.
`house_system`	string	No	Default `placidus`. Affects planet house placement and therefore hemisphere counts.
`node_type`	string	No	`true`, `mean`, or `both`. Default `true`.

Hemisphere definitions

Hemisphere	Houses	Meaning
Eastern	10, 11, 12, 1, 2, 3 (ASC side)	Self-directed, independent, personal initiative
Western	4, 5, 6, 7, 8, 9 (DSC side)	Other-directed, responsive to environment, relationships
Northern	1, 2, 3, 4, 5, 6 (below horizon)	Private, subjective, inner life, foundations
Southern	7, 8, 9, 10, 11, 12 (above horizon)	Public, objective, outer life, career and reputation

Quadrants

Quadrant	Houses	Theme
First (NE)	1, 2, 3	Personal identity and self-expression
Second (NW)	4, 5, 6	Personal resources, home, daily service
Third (SW)	7, 8, 9	Relationships, shared resources, philosophy
Fourth (SE)	10, 11, 12	Career, community, spirituality

Response shape

`data.hemispheres.{name}`

Field	Type	Description
`count`	integer	Number of planets in this hemisphere.
`percentage`	number	Percentage of total planets.
`planets`	array	Planet names in this hemisphere.
`meaning`	string	Brief interpretation of emphasis.

Emphasis fields

Field	Values	Description
`east_west_emphasis`	`eastern`, `western`, `balanced`	Which horizontal half dominates.
`north_south_emphasis`	`northern`, `southern`, `balanced`	Which vertical half dominates.
`dominant_quadrant`	`first`–`fourth`	Quadrant with most planets.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	Required field absent.
400	`INVALID_DATE`	Invalid date.
400	`INVALID_TIME`	Time outside range.
400	`INVALID_TIMEZONE`	Not valid IANA.
400	`INVALID_COORDINATE`	Out of range.
400	`INVALID_PARAM`	Invalid `house_system`.
500	`EPHEMERIS_ERROR`	Computation failed.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/western/natal/hemisphere-balance" \
  -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"
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/western/natal/hemisphere-balance',
  {
    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'
    })
  }
);
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/natal/hemisphere-balance',
    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'
    }
)
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',
];

$ch = curl_init('https://starsapi.com/api/v3/western/natal/hemisphere-balance');
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/natal/hemisphere-balance'),
    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',
    }),
  );
  return jsonDecode(response.body);
}

import Foundation

func getAscendant() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/western/natal/hemisphere-balance"
    )!)
    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"
        }
        """.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"
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/western/natal/hemisphere-balance")
        .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",
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/western/natal/hemisphere-balance",
        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/natal/hemisphere-balance')
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'
}

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": {
    "hemispheres": {
      "eastern":  { "count": 5, "percentage": 38.5, "planets": ["Moon","Venus","Jupiter","Saturn","Uranus"], "meaning": "Self-directed, independent" },
      "western":  { "count": 8, "percentage": 61.5, "planets": ["Sun","Mercury","Mars","Neptune","Pluto","Chiron","Lilith","North Node"], "meaning": "Other-directed, relationships" },
      "northern": { "count": 9, "percentage": 69.2, "planets": ["Sun","Mercury","Venus","Mars","Saturn","Uranus","Neptune","Pluto","Chiron"], "meaning": "Private, inner life" },
      "southern": { "count": 4, "percentage": 30.8, "planets": ["Moon","Jupiter","Lilith","North Node"], "meaning": "Public, outer life" }
    },
    "quadrants": {
      "first":  { "houses": [1,2,3], "count": 3, "percentage": 23.1, "planets": ["Venus","Saturn","Uranus"], "meaning": "Personal identity" },
      "second": { "houses": [4,5,6], "count": 6, "percentage": 46.2, "planets": ["Sun","Mercury","Mars","Neptune","Pluto","Chiron"], "meaning": "Personal resources, service" },
      "third":  { "houses": [7,8,9], "count": 2, "percentage": 15.4, "planets": ["Lilith","North Node"], "meaning": "Relationships, philosophy" },
      "fourth": { "houses": [10,11,12], "count": 2, "percentage": 15.4, "planets": ["Moon","Jupiter"], "meaning": "Career, community" }
    },
    "east_west_emphasis": "western",
    "north_south_emphasis": "northern",
    "dominant_quadrant": "second",
    "total_planets": 13
  },
  "meta": { "endpoint": "/api/v3/western/natal/hemisphere-balance", "version": "3.0" }
}