Planetary Aspects

Endpoint POST https://starsapi.com/api/v3/vedic/natal/planetary-aspects

Returns planet-to-planet Parashari graha drishti for the 9 Vedic grahas. Every planet casts a full 7th-house aspect. Mars additionally aspects the 4th and 8th houses from its position; Jupiter the 5th and 9th; Saturn the 3rd and 10th; Rahu and Ketu the 5th, 7th, and 9th.

Each aspect includes the source and target planets, their signs and houses, the aspect type (e.g. 7th, 4th, 9th), the exact degree distance, and an aspect strength score on a 0–60 virupa scale. Rahu–Ketu mutual aspects are excluded since the nodes are always exactly 180° apart. For a house-level view (which planets aspect each house), use /natal/planets-in-houses instead.

Authentication

Required. Three methods accepted:

Method	Example
Header (recommended)	`X-Api-Key: am_live_xxxxxxxxxxxx`
Bearer	`Authorization: Bearer am_live_xxxxxxxxxxxx`
Query	`?api_key=am_live_xxxxxxxxxxxx`

See authentication for security considerations.

Request body

Send a JSON object with Content-Type: application/json. All core fields are required.

Field	Type	Required	Description
`year`	integer	Yes	Birth year, 4-digit (e.g. `1990`).
`month`	integer	Yes	Birth month, `1`–`12`.
`day`	integer	Yes	Day of month, `1`–`31`.
`hour`	integer	Yes	Hour in 24-hour local clock time, `0`–`23`.
`minute`	integer	Yes	Minute, `0`–`59`.
`second`	integer	No	Second, `0`–`59`. Default `0`.
`latitude`	number	Yes	Signed decimal degrees, −90…90. Positive = North (e.g. `28.6139`).
`longitude`	number	Yes	Signed decimal degrees, −180…180. Positive = East (e.g. `77.2090`).
`timezone`	string	Yes	IANA timezone identifier (e.g. `Asia/Kolkata`). DST is resolved automatically.
`name`	string	No	Native’s name. Not returned by this endpoint; use `/vedic/birth-details` to retrieve it.
`place`	string	No	Birth place label. Not returned by this endpoint; use `/vedic/birth-details` to retrieve it.
`ayanamsa`	string	No	Sidereal mode. Default `lahiri`. Full list of 45+ ayanamsas →
`node_type`	string	No	`mean` (default) or `true`. Controls Rahu/Ketu position calculation.

Use the local clock time of birth. Pass the wall-clock time as recorded on the birth certificate together with the IANA timezone of the birth place — the backend converts to UTC internally. Do not pre-convert to UTC yourself.

Response shape

The data.aspects array contains one object per planet-to-planet aspect found. Only aspects where the two planets are within a 15° orb are included. Birth input is not echoed back — call /vedic/birth-details separately to retrieve resolved birth details.

Field	Type	Description
aspects[]
`source`	string	The planet casting the aspect.
`target`	string	The planet receiving the aspect.
`aspect_type`	string	Which house distance: `7th` (standard, all planets), `3rd`/`10th` (Saturn), `4th`/`8th` (Mars), `5th`/`9th` (Jupiter, Rahu, Ketu).
`source_sign`	string	Sign the source planet occupies.
`target_sign`	string	Sign the target planet occupies.
`source_house`	integer	House the source planet occupies (1–12).
`target_house`	integer	House the target planet occupies (1–12).
`degree_distance`	number	Distance in degrees from exact aspect (0–15). Lower = tighter.
`strength`	number	Aspect strength on a 0–60 virupa scale. Formula: `60 × (1 − degree_distance / 15)`. 60 = exact, 0 = at orb boundary.
top-level
`total_aspects`	integer	Total number of aspects found.
meta
`meta.endpoint`	string	Echo of the called endpoint path.
`meta.version`	string	API version (currently `3.0`).
`meta.response_time_ms`	integer	Server-side response time in milliseconds.
`meta.timestamp`	string (ISO 8601)	Time the response was served.
`meta.credits_remaining`	integer	API credits remaining on your plan.
`meta.request_id`	string	Unique request identifier — include in support tickets.
`meta.ayanamsa.name`	string	Sidereal mode applied.
`meta.ayanamsa.value`	number	Ayanamsa offset in decimal degrees.
`meta.ayanamsa.value_dms`	string	Same in D°M′S″ format.
`meta.node_type`	string	Rahu/Ketu calculation mode: `mean` or `true`.

Aspect rules

Parashari graha drishti follows fixed rules by planet:

Planet	Aspects cast
All planets	7th house from their position (standard opposition).
Mars	4th and 8th (in addition to 7th).
Jupiter	5th and 9th (in addition to 7th).
Saturn	3rd and 10th (in addition to 7th).
Rahu / Ketu	5th, 7th, and 9th. Mutual Rahu–Ketu aspects are excluded (always 180° apart).

Strength calculation

Aspect strength is a linear function of how close the two planets are to the exact aspect point. The formula is:

strength = 60 × (1 − degree_distance / 15)

At exact aspect (degree_distance = 0), strength is 60 virupa (full). At the 15° orb boundary, strength drops to 0. Only aspects within this 15° window are returned.

Use cases

Aspect grid — render a 9×9 planet matrix showing who aspects whom, with strength as colour intensity.
Yoga detection — scan the list for specific source–target pairs to identify classical yogas (e.g. Gajakesari: Jupiter aspecting Moon).
Strength filtering — surface only tight aspects (strength > 30) for quick analysis, or include weaker ones for detailed work.
House-based grouping — use source_house / target_house to see which bhavas are connected by planetary glances.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	A required birth field is absent.
400	`INVALID_DATE`	Invalid calendar date.
400	`INVALID_TIME`	Hour/minute/second out of range.
400	`INVALID_TIMEZONE`	Numeric or non-IANA timezone.
400	`INVALID_COORDINATE`	`latitude` / `longitude` out of range.
401	`AUTH_MISSING_KEY`	No API key in request.
401	`AUTH_INVALID_KEY`	Key format invalid or not found.
401	`AUTH_REVOKED_KEY`	Key has been revoked.
403	`AUTH_ORIGIN_DENIED`	Request from non-whitelisted origin.
405	`METHOD_NOT_ALLOWED`	Non-POST request.
429	`RATE_LIMIT_EXCEEDED`	Plan quota exceeded.
500	`CALCULATION_ERROR`	Ephemeris calculation failed.

Error response format

{
  "success": false,
  "error": {
    "code": "INVALID_TIMEZONE",
    "message": "Unrecognised timezone: 'Asia/Calcutta_'. Use a valid IANA identifier such as 'Asia/Kolkata'."
  }
}

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

const response = await fetch(
  'https://starsapi.com/api/v3/vedic/natal/planetary-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'
    })
  }
);
const result = await response.json();

if (result.success) {
  console.log(result.data);
}

import requests
import os

response = requests.post(
    'https://starsapi.com/api/v3/vedic/natal/planetary-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'
    }
)
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',
];

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

import Foundation

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

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

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/vedic/natal/planetary-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/vedic/natal/planetary-aspects')
payload = {
  'year' => 1990,
  'month' => 5,
  'day' => 20,
  'hour' => 14,
  'minute' => 30,
  'second' => 0,
  'latitude' => 28.6139,
  'longitude' => 77.209,
  'timezone' => 'Asia/Kolkata'
}

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": [
      {
        "source": "Mars",
        "target": "Sun",
        "aspect_type": "4th",
        "source_sign": "Aquarius",
        "target_sign": "Taurus",
        "source_house": 6,
        "target_house": 9,
        "degree_distance": 7.1434,
        "strength": 31.43
      },
      {
        "source": "Jupiter",
        "target": "Mars",
        "aspect_type": "9th",
        "source_sign": "Gemini",
        "target_sign": "Aquarius",
        "source_house": 10,
        "target_house": 6,
        "degree_distance": 11.471,
        "strength": 14.12
      },
      {
        "source": "Saturn",
        "target": "Moon",
        "aspect_type": "3rd",
        "source_sign": "Capricorn",
        "target_sign": "Pisces",
        "source_house": 5,
        "target_house": 7,
        "degree_distance": 6.3188,
        "strength": 34.72
      },
      {
        "source": "Saturn",
        "target": "Venus",
        "aspect_type": "3rd",
        "source_sign": "Capricorn",
        "target_sign": "Pisces",
        "source_house": 5,
        "target_house": 7,
        "degree_distance": 6.7509,
        "strength": 33
      },
      {
        "source": "Saturn",
        "target": "Ketu",
        "aspect_type": "7th",
        "source_sign": "Capricorn",
        "target_sign": "Cancer",
        "source_house": 5,
        "target_house": 11,
        "degree_distance": 14.0673,
        "strength": 3.73
      },
      {
        "source": "Rahu",
        "target": "Sun",
        "aspect_type": "5th",
        "source_sign": "Capricorn",
        "target_sign": "Taurus",
        "source_house": 5,
        "target_house": 9,
        "degree_distance": 11.9882,
        "strength": 12.05
      },
      {
        "source": "Ketu",
        "target": "Saturn",
        "aspect_type": "7th",
        "source_sign": "Cancer",
        "target_sign": "Capricorn",
        "source_house": 11,
        "target_house": 5,
        "degree_distance": 14.0673,
        "strength": 3.73
      },
      {
        "source": "Ketu",
        "target": "Moon",
        "aspect_type": "9th",
        "source_sign": "Cancer",
        "target_sign": "Pisces",
        "source_house": 11,
        "target_house": 7,
        "degree_distance": 9.6139,
        "strength": 21.54
      },
      {
        "source": "Ketu",
        "target": "Venus",
        "aspect_type": "9th",
        "source_sign": "Cancer",
        "target_sign": "Pisces",
        "source_house": 11,
        "target_house": 7,
        "degree_distance": 7.3164,
        "strength": 30.73
      }
    ],
    "total_aspects": 9
  },
  "meta": {
    "endpoint": "/api/v3/vedic/natal/planetary-aspects",
    "version": "3.0",
    "response_time_ms": 8,
    "timestamp": "2026-06-09T05:40:21+05:30",
    "credits_remaining": 198606,
    "request_id": "d19a102ac95a2daf",
    "ayanamsa": {
      "name": "Lahiri",
      "value": 23.725957,
      "value_dms": "23°43'33\""
    },
    "node_type": "mean"
  }
}