Elemental Balance

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

Analyzes the distribution of 10 classical planets plus the Ascendant (11 points) across the four elements — Fire, Earth, Air, and Water. Returns the full distribution with planet lists and percentages, plus prewritten interpretations with keyword pills for both the dominant and lacking elements.

Element mapping

Element	Signs
Fire	Aries, Leo, Sagittarius
Earth	Taurus, Virgo, Capricorn
Air	Gemini, Libra, Aquarius
Water	Cancer, Scorpio, Pisces

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	Birth second, default 0.
`latitude`	number	Yes	Decimal degrees.
`longitude`	number	Yes	Decimal degrees.
`timezone`	string	Yes	IANA timezone.
`language`	string	No	Language code. Default `en`.
`house_system`	string	No	Default `placidus`.

Response shape

Field	Type	Description
`distribution`	object	Four keys (`fire`, `earth`, `air`, `water`), each with `count`, `planets` array, and `percentage`.
`dominant`	object	Element with highest count. Includes `element`, `count`, `percentage`, and `prediction`.
`lacking`	object	Element with lowest count. Same shape as dominant.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	Required field absent.
400	`INVALID_DATE`	Bad calendar date.
400	`INVALID_TIMEZONE`	Non-IANA timezone.
400	`INVALID_COORDINATE`	Lat/lon out of range.
405	`METHOD_NOT_ALLOWED`	Non-POST request.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/western/predictions/elemental-balance" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Priya",
        "gender": "female",
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "language": "en"
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/western/predictions/elemental-balance',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Priya',
      gender: 'female',
      year: 1990,
      month: 5,
      day: 20,
      hour: 14,
      minute: 30,
      second: 0,
      latitude: 28.6139,
      longitude: 77.209,
      timezone: 'Asia/Kolkata',
      language: 'en'
    })
  }
);
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/predictions/elemental-balance',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    json={
        'name': 'Priya',
        'gender': 'female',
        'year': 1990,
        'month': 5,
        'day': 20,
        'hour': 14,
        'minute': 30,
        'second': 0,
        'latitude': 28.6139,
        'longitude': 77.209,
        'timezone': 'Asia/Kolkata',
        'language': 'en'
    }
)
result = response.json()

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

<?php
$payload = [
    'name' => 'Priya',
    'gender' => 'female',
    'year' => 1990,
    'month' => 5,
    'day' => 20,
    'hour' => 14,
    'minute' => 30,
    'second' => 0,
    'latitude' => 28.6139,
    'longitude' => 77.209,
    'timezone' => 'Asia/Kolkata',
    'language' => 'en',
];

$ch = curl_init('https://starsapi.com/api/v3/western/predictions/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/predictions/elemental-balance'),
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'name': 'Priya',
      'gender': 'female',
      'year': 1990,
      'month': 5,
      'day': 20,
      'hour': 14,
      'minute': 30,
      'second': 0,
      'latitude': 28.6139,
      'longitude': 77.209,
      'timezone': 'Asia/Kolkata',
      'language': 'en',
    }),
  );
  return jsonDecode(response.body);
}

import Foundation

func getAscendant() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/western/predictions/elemental-balance"
    )!)
    request.httpMethod = "POST"
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = """
        {
            "name": "Priya",
            "gender": "female",
            "year": 1990,
            "month": 5,
            "day": 20,
            "hour": 14,
            "minute": 30,
            "second": 0,
            "latitude": 28.6139,
            "longitude": 77.209,
            "timezone": "Asia/Kolkata",
            "language": "en"
        }
        """.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 = """
    {
        "name": "Priya",
        "gender": "female",
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "language": "en"
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/western/predictions/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{}{
        "name": "Priya",
        "gender": "female",
        "year": 1990,
        "month": 5,
        "day": 20,
        "hour": 14,
        "minute": 30,
        "second": 0,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
        "language": "en",
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/western/predictions/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/predictions/elemental-balance')
payload = {
  'name' => 'Priya',
  'gender' => 'female',
  'year' => 1990,
  'month' => 5,
  'day' => 20,
  'hour' => 14,
  'minute' => 30,
  'second' => 0,
  'latitude' => 28.6139,
  'longitude' => 77.209,
  'timezone' => 'Asia/Kolkata',
  'language' => 'en'
}

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": {
    "language": "en",
    "elemental_balance": {
      "distribution": {
        "fire": {"count": 2, "planets": ["Moon", "Venus"], "percentage": 18.2},
        "earth": {"count": 6, "planets": ["Sun", "Mercury", "Saturn", "Uranus", "Neptune", "Asc"], "percentage": 54.5},
        "air": {"count": 0, "planets": [], "percentage": 0},
        "water": {"count": 3, "planets": ["Mars", "Jupiter", "Pluto"], "percentage": 27.3}
      },
      "dominant": {
        "element": "Earth",
        "count": 6,
        "percentage": 54.5,
        "prediction": {
          "title": "Earth Dominant Chart",
          "text": "Your chart is grounded in the element of practicality…",
          "keywords": ["Practical builder", "Sensory intelligence", "Patient endurance", "Results-oriented"]
        }
      },
      "lacking": {
        "element": "Air",
        "count": 0,
        "percentage": 0,
        "prediction": {
          "title": "Lacking Air",
          "text": "With minimal air energy in your chart…",
          "keywords": ["Experiential learner", "Show over tell", "Developing objectivity", "Direct engagement"]
        }
      }
    }
  },
  "meta": { "endpoint": "/api/v3/western/predictions/elemental-balance", "version": "3.0" }
}