Elemental Balance

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

Overview

Computes the elemental distribution of planets across Fire, Earth, Air, and Water. Returns both raw counts and weighted scores where Sun, Moon, and Ascendant carry double weight (reflecting their outsized influence on personality). Each element includes the list of planets placed in it.

A missing element (zero planets) is astrologically significant — it often indicates an area the native must consciously develop. The response flags any missing elements explicitly.

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 (−90 to 90).
`longitude`	number	Yes	Decimal degrees (−180 to 180).
`timezone`	string	Yes	IANA timezone.
`house_system`	string	No	Default `placidus`. 25 systems supported. See house systems.
`node_type`	string	No	`true`, `mean`, or `both`. Default `true`.

Response shape

`data.distribution.{element}`

Field	Type	Description
`count`	integer	Number of bodies in this element.
`weighted`	integer	Weighted score (Sun, Moon, Ascendant count double).
`percentage`	number	Percentage of total bodies.
`weighted_percentage`	number	Percentage of weighted total.
`planets`	array	Names of bodies in this element (includes `"Ascendant"` if applicable).

Other fields

Field	Type	Description
`dominant`	string	Element with highest weighted score.
`weakest`	string	Element with lowest weighted score.
`missing_elements`	array	Elements with zero planets. Empty array if all represented.
`total_points`	integer	Total unweighted body count.
`total_weighted`	integer	Total weighted score.

Weighting system

Body	Weight	Rationale
Sun	2	Core identity, life force.
Moon	2	Emotional nature, instinctive reactions.
Ascendant	2	Physical appearance, how others perceive you.
All other planets	1	Standard weight.

South Node and Part of Fortune are excluded from the count (South Node is always opposite North Node; Part of Fortune is a calculated lot, not a body).

Element → Signs reference

Element	Signs	Keywords
Fire	Aries, Leo, Sagittarius	Energy, enthusiasm, action, inspiration
Earth	Taurus, Virgo, Capricorn	Practicality, stability, material focus
Air	Gemini, Libra, Aquarius	Intellect, communication, social connection
Water	Cancer, Scorpio, Pisces	Emotion, intuition, depth, sensitivity

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	A required field is absent.
400	`INVALID_DATE`	Invalid date or year outside range.
400	`INVALID_TIME`	Hour/minute/second outside range.
400	`INVALID_TIMEZONE`	Not a valid IANA identifier.
400	`INVALID_COORDINATE`	Latitude or longitude out of range.
400	`INVALID_PARAM`	Invalid `house_system`.
500	`EPHEMERIS_ERROR`	Swiss Ephemeris computation failed.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/western/natal/elemental-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/elemental-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/elemental-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/elemental-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/elemental-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/elemental-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/elemental-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/elemental-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/elemental-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": {
    "distribution": {
      "Earth": {
        "count": 6,
        "weighted": 8,
        "percentage": 40.0,
        "weighted_percentage": 47.1,
        "planets": ["Sun", "Mercury", "Ascendant", "Uranus", "Neptune", "Pluto"]
      },
      "Water": {
        "count": 5,
        "weighted": 5,
        "percentage": 33.3,
        "weighted_percentage": 29.4,
        "planets": ["Jupiter", "Mars", "Chiron", "Lilith", "North Node"]
      },
      "Fire": {
        "count": 2,
        "weighted": 3,
        "percentage": 13.3,
        "weighted_percentage": 17.6,
        "planets": ["Moon", "Venus"]
      },
      "Air": {
        "count": 1,
        "weighted": 1,
        "percentage": 6.7,
        "weighted_percentage": 5.9,
        "planets": ["Saturn"]
      }
    },
    "dominant": "Earth",
    "weakest": "Air",
    "missing_elements": [],
    "total_points": 14,
    "total_weighted": 17
  },
  "meta": {
    "endpoint": "/api/v3/western/natal/elemental-balance",
    "version": "3.0",
    "response_time_ms": 12
  }
}