Docs
Western Astrology
Natal
Natal Aspects

POST · WESTERN

Natal Aspects

Endpoint POST https://starsapi.com/api/v3/western/natal/aspects

Overview

Computes all natal aspects between the 15 celestial bodies. Each aspect includes both planets’ absolute tropical longitude, sign degree, orb, exactness percentage, phase (applying, separating, or exact), nature, and a description. Results are sorted by exactness (tightest first).

Supports custom orbs per aspect type (0–15°), and toggle for minor aspects. Luminaries (Sun and Moon) automatically receive wider orbs than the base values.

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`. See house systems.
`node_type`	string	No	`true`, `mean`, or `both`. Default `true`.
`include_minor_aspects`	boolean	No	Include minor aspects. Default `true`.
`custom_orbs`	object	No	Override default orbs per aspect type. See below.

Custom orbs

Pass custom_orbs to override the default orb for any aspect type. Values must be between 0 and 15 degrees. Invalid aspect names or out-of-range values return a 400 INVALID_PARAM error.

{
  "custom_orbs": {
    "conjunction": 10,
    "trine": 6,
    "square": 5,
    "sextile": 4,
    "quincunx": 2
  }
}

Default orbs:

Aspect	Default orb	Type
Conjunction	8°	Major
Opposition	8°	Major
Trine	8°	Major
Square	7°	Major
Sextile	6°	Major
Quincunx	3°	Minor
Semi-sextile	2°	Minor
Semi-square	2°	Minor
Sesquiquadrate	2°	Minor
Quintile	2°	Minor
Bi-quintile	2°	Minor

Sun and Moon automatically receive wider orbs (luminary adjustment) above these base values.

Valid custom_orbs keys: conjunction, opposition, trine, square, sextile, quincunx, semi_sextile, semi_square, sesquiquadrate, quintile, bi_quintile.

Response shape

`data.aspects[]`

Array of aspect objects sorted by orb (tightest first):

Field	Type	Description
`planet1`	string	First planet name.
`planet1_longitude`	number	Absolute tropical longitude (0–360). Plottable on a 360° chart circle.
`planet1_sign`	string	Zodiac sign.
`planet1_sign_degree`	number	Numeric degree within sign (0–29.99). Sortable.
`planet1_degree`	string	DMS degree within sign (display).
`planet2`	string	Second planet name.
`planet2_longitude`	number	Absolute longitude.
`planet2_sign`	string	Sign.
`planet2_sign_degree`	number	Numeric degree within sign.
`planet2_degree`	string	DMS display.
`aspect`	string	Display name (e.g. `"Trine"`).
`aspect_key`	string	Programmatic key (e.g. `"trine"`).
`symbol`	string	Unicode aspect symbol.
`angle`	integer	Exact aspect angle in degrees (e.g. 120).
`orb`	number	Actual deviation from exact in degrees.
`max_orb`	number	Maximum allowed orb (after luminary adjustments).
`exactness_percent`	number	How close to exact (100 = partile, 0 = edge of orb).
`phase`	string	`"applying"` (tightening), `"separating"` (loosening), or `"exact"` (orb < 0.01°).
`nature`	string	`"harmonious"`, `"challenging"`, `"variable"`, `"stressful"`, `"mild"`, or `"creative"`.
`is_major`	boolean	True for the 5 major aspects.
`description`	string	Brief interpretation of the aspect type.

`data.aspects_by_planet`

Same aspects grouped by planet name, for quick lookup of all aspects involving a specific body.

`data.aspect_summary`

Object counting aspects by type (e.g. {"conjunction": 3, "trine": 5, "square": 4}).

Aspect types reference

Key	Name	Angle	Symbol	Nature	Category
`conjunction`	Conjunction	0°	☌	variable	Major
`opposition`	Opposition	180°	☍	challenging	Major
`trine`	Trine	120°	△	harmonious	Major
`square`	Square	90°	□	challenging	Major
`sextile`	Sextile	60°	⚹	harmonious	Major
`quincunx`	Quincunx	150°	⚻	stressful	Minor
`semi_sextile`	Semi-sextile	30°	⚺	mild	Minor
`semi_square`	Semi-square	45°	∠	challenging	Minor
`sesquiquadrate`	Sesquiquadrate	135°	⚼	challenging	Minor
`quintile`	Quintile	72°	Q	creative	Minor
`bi_quintile`	Bi-quintile	144°	bQ	creative	Minor

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	A required field is absent.
400	`INVALID_DATE`	Invalid calendar date or year outside range.
400	`INVALID_TIME`	Hour/minute/second outside valid range.
400	`INVALID_TIMEZONE`	Not a valid IANA identifier.
400	`INVALID_COORDINATE`	Latitude or longitude out of range.
400	`INVALID_PARAM`	Invalid `house_system`, or `custom_orbs` with unknown aspect key or value outside 0–15.
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/aspects" \
  -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",
        "include_minor_aspects": true
    }'

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

$ch = curl_init('https://starsapi.com/api/v3/western/natal/aspects');
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/aspects'),
    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',
      'include_minor_aspects': 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/aspects"
    )!)
    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",
            "include_minor_aspects": 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",
        "include_minor_aspects": true
    }
    """.trimIndent()

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

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/western/natal/aspects",
        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/aspects')
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',
  'include_minor_aspects' => 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": {
    "aspects": [
      {
        "planet1": "Mars",
        "planet1_longitude": 351.9494,
        "planet1_sign": "Pisces",
        "planet1_sign_degree": 21.9494,
        "planet1_degree": "21°56'58\"",
        "planet2": "Lilith",
        "planet2_longitude": 232.025,
        "planet2_sign": "Scorpio",
        "planet2_sign_degree": 22.025,
        "planet2_degree": "22°01'30\"",
        "aspect": "Trine",
        "aspect_key": "trine",
        "symbol": "△",
        "angle": 120,
        "orb": 0.08,
        "max_orb": 8,
        "exactness_percent": 99.1,
        "phase": "applying",
        "nature": "harmonious",
        "is_major": true,
        "description": "Easy flow of energy — natural talent and gifts"
      }
    ],
    "aspects_by_planet": { "Mars": [ "..." ] },
    "aspect_summary": { "conjunction": 3, "trine": 5, "square": 4 },
    "total_aspects": 42,
    "include_minor": true
  },
  "meta": {
    "endpoint": "/api/v3/western/natal/aspects",
    "version": "3.0",
    "response_time_ms": 15
  }
}