POST
Aspects - Western Astrology
Calculate planetary aspects in Western astrology for a given date, time, and geographical location. Identify aspects such as conjunctions, oppositions, trines, squares, and sextiles, with configurable aspect filters, orb values, and planet exclusions for customized natal chart analysis.
/western/aspects
Method
POST
Format
JSON
Auth
API Key
Credits
1
Overview
The Western Astrology Aspects API calculates astrological aspects between pairs of planets and supported chart points for a specified date, time, and geographical location. It identifies angular relationships such as conjunction, opposition, trine, square, sextile, semi-sextile, quintile, septile, octile, novile, quincunx, and sesquiquadrate.
Each aspect result identifies the two objects involved and the aspect connecting them. Supported objects include the Sun, Moon, planets, lunar nodes, Ascendant, Descendant, Midheaven (MC), Imum Coeli (IC), and selected additional astrological points. Developers can use these results to build aspect tables, natal chart visualizations, and Western astrology interpretation tools.
To calculate aspects, provide the year, month, date, time, latitude, longitude, and timezone. Optional configuration settings allow you to exclude selected objects, include only specified aspect types, and customize the orb value for each aspect. You can also choose the zodiac calculation mode, observation point, and supported response language. The API returns structured JSON data for integration into websites, mobile applications, and astrology software.
Request Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
year
|
integer | Yes | Year number, eg: 2023 | 2023 |
month
|
integer | Yes | Month number,with no leading zero | 7 |
date
|
integer | Yes | Day number,with no leading zero | 5 |
hours
|
integer | Yes | Hours number,with no leading zero | 1 |
minutes
|
integer | Yes | Minutes number,with no leading zero | 1 |
seconds
|
integer | Yes | Seconds number, with no leading zero | 0 |
latitude
|
float | Yes | Latitude number, in the range from -90 to 90 | 12.86 |
longitude
|
float | Yes | Longitude number, in the range from -180 to 180 | 123.5 |
timezone
|
float | Yes | Timezone of birth location, eg: 5.5 | 5.5 |
config
|
object | No | Contains optional configuration values | |
ayanamsha
|
string | No | Either "tropical" or "sayana" or "lahiri" | Either "tropical" or "sayana" or "lahiri" |
language
|
string | No | Valid 2 letter ISO 639-1 language code | Either "en" For English or "es" for Spanish or "fr" for French or "pt" for Portuguese or "ru" for Russian or "de" for German or "ja" for Japanese or "pl" for Polish or "tr" for Turkish |
observation_point
|
string | No | Geocentric positions are calculated with respect to the center of Earth. Topocentric positions are calculated with respect to the actual given place | Either "topocentric" or "geocentric" |
exclude_planets
|
array | No | Array of Planets, which you want to be excluded. By default all the planets will be considered. For example, ["Lilith","Chiron"] will exclude Lilith,Chiron for calculating aspects. | ["Lilith","Chiron"] |
allowed_aspects
|
array | No | Array of Aspects, only which you want to be included. By default all the above aspects will be considered. | For example ["Conjunction","Trine"] will consider only Conjunction and Trine. |
orb_values
|
object | No | For each aspect, a custom orb can be mentioned. Range from 0 to 15 | {"Conjunction": 3, "Opposition": 5, "Square": 5, "Trine": 5} |
Supported Languages
This API endpoint supports the following languages.
Use the corresponding 2-letter language code
in the language parameter when making your request.
| Language | Code |
|---|---|
| English |
en
|
| Spanish |
es
|
| French |
fr
|
| Portuguese |
pt
|
| Russian |
ru
|
| German |
de
|
| Japanese |
ja
|
| Polish |
pl
|
| Turkish |
tr
|
Example
To request the response in Telugu, use
te as the language code:
{
"language": "te"
}Request Example
{
"year": 1998,
"month": 3,
"date": 3,
"hours": 10,
"minutes": 30,
"seconds": 0,
"latitude": 17.38405,
"longitude": 78.45636,
"timezone": 5.5,
"config": {
"observation_point": "topocentric", /* geocentric or topocentric */
"ayanamsha": "tropical", /* tropical or sayana or lahiri */
"language": "en", /* en , te , es , fr , pt , ru , de , ja */
"exclude_planets": ["Lilith","Chiron","Ceres","Vesta","Juno","Pallas"], /* "True Node", "Mean Node", "IC","MC","Descendant","Ascendant","Sun","Moon","Mars","Mercury","Jupiter","Venus","Saturn","Lilith","Chiron","Ceres","Vesta","Juno","Pallas","Uranus","Neptune","Pluto"*/
"allowed_aspects": ["Conjunction","Trine"], /* "Conjunction", "Opposition", "Trine","Square","Sextile","Semi-Sextile","Quintile","Septile","Octile","Novile","Quincunx","Sesquiquadrate" */
"orb_values":{
"Conjunction": 3,
"Opposition": 5,
"Square": 5,
"Trine": 5,
"Sextile": 5,
"Semi-Sextile": 5,
"Quintile": 5,
"Septile": 5,
"Octile": 5,
"Novile": 5,
"Quincunx": 5,
"Sesquiquadrate": 5
}
}
}
Response Examples
Example responses returned by this API.
English Response
{
"statusCode": 200,
"output": [
{
"planet_1": {
"en": "Moon"
},
"planet_2": {
"en": "Mean Node"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Moon"
},
"planet_2": {
"en": "True Node"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mercury"
},
"planet_2": {
"en": "Descendant"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Venus"
},
"planet_2": {
"en": "Neptune"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Uranus"
},
"planet_2": {
"en": "MC"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Pluto"
},
"planet_2": {
"en": "IC"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mean Node"
},
"planet_2": {
"en": "True Node"
},
"aspect": {
"en": "Conjunction"
}
}
]
}
Spanish Response
{
"statusCode": 200,
"output": [
{
"planet_1": {
"en": "Moon",
"es": "Luna"
},
"planet_2": {
"en": "Mean Node",
"es": "Nodo Medio"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Moon",
"es": "Luna"
},
"planet_2": {
"en": "True Node",
"es": "Nodo Verdadero"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mercury",
"es": "Mercurio"
},
"planet_2": {
"en": "Descendant",
"es": "Descendente"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Venus",
"es": "Venus"
},
"planet_2": {
"en": "Neptune",
"es": "Neptuno"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Uranus",
"es": "Urano"
},
"planet_2": {
"en": "MC",
"es": "Medio Cielo"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Pluto",
"es": "Plutón"
},
"planet_2": {
"en": "IC",
"es": "Fondo del Cielo"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mean Node",
"es": "Nodo Medio"
},
"planet_2": {
"en": "True Node",
"es": "Nodo Verdadero"
},
"aspect": {
"en": "Conjunction"
}
}
]
}
French Response
{
"statusCode": 200,
"output": [
{
"planet_1": {
"en": "Moon",
"fr": "Lune"
},
"planet_2": {
"en": "Mean Node",
"fr": "Nœud moyen"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Moon",
"fr": "Lune"
},
"planet_2": {
"en": "True Node",
"fr": "Nœud vrai"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mercury",
"fr": "Mercure"
},
"planet_2": {
"en": "Descendant",
"fr": "Descendant"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Venus",
"fr": "Vénus"
},
"planet_2": {
"en": "Neptune",
"fr": "Neptune"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Uranus",
"fr": "Uranus"
},
"planet_2": {
"en": "MC",
"fr": "Milieu du Ciel"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Pluto",
"fr": "Pluton"
},
"planet_2": {
"en": "IC",
"fr": "Imum Coeli"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mean Node",
"fr": "Nœud moyen"
},
"planet_2": {
"en": "True Node",
"fr": "Nœud vrai"
},
"aspect": {
"en": "Conjunction"
}
}
]
}
Portuguese Response
{
"statusCode": 200,
"output": [
{
"planet_1": {
"en": "Moon",
"pt": "Lua"
},
"planet_2": {
"en": "Mean Node",
"pt": "Nodo Médio"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Moon",
"pt": "Lua"
},
"planet_2": {
"en": "True Node",
"pt": "Nodo Verdadeiro"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mercury",
"pt": "Mercúrio"
},
"planet_2": {
"en": "Descendant",
"pt": "Descendente"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Venus",
"pt": "Vênus"
},
"planet_2": {
"en": "Neptune",
"pt": "Netuno"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Uranus",
"pt": "Urano"
},
"planet_2": {
"en": "MC",
"pt": "Meio do Céu"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Pluto",
"pt": "Plutão"
},
"planet_2": {
"en": "IC",
"pt": "Fundo do Céu"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mean Node",
"pt": "Nodo Médio"
},
"planet_2": {
"en": "True Node",
"pt": "Nodo Verdadeiro"
},
"aspect": {
"en": "Conjunction"
}
}
]
}
Russian Response
{
"statusCode": 200,
"output": [
{
"planet_1": {
"en": "Moon",
"ru": "Луна"
},
"planet_2": {
"en": "Mean Node",
"ru": "Средний узел"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Moon",
"ru": "Луна"
},
"planet_2": {
"en": "True Node",
"ru": "Истинный узел"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mercury",
"ru": "Меркурий"
},
"planet_2": {
"en": "Descendant",
"ru": "Десцендент"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Venus",
"ru": "Венера"
},
"planet_2": {
"en": "Neptune",
"ru": "Нептун"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Uranus",
"ru": "Уран"
},
"planet_2": {
"en": "MC",
"ru": "Медиум Цели"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Pluto",
"ru": "Плутон"
},
"planet_2": {
"en": "IC",
"ru": "Имум Цели"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mean Node",
"ru": "Средний узел"
},
"planet_2": {
"en": "True Node",
"ru": "Истинный узел"
},
"aspect": {
"en": "Conjunction"
}
}
]
}
German Response
{
"statusCode": 200,
"output": [
{
"planet_1": {
"en": "Moon",
"de": "Mond"
},
"planet_2": {
"en": "Mean Node",
"de": "Mittlerer Knoten"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Moon",
"de": "Mond"
},
"planet_2": {
"en": "True Node",
"de": "Echter Knoten"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mercury",
"de": "Merkur"
},
"planet_2": {
"en": "Descendant",
"de": "Deszendent"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Venus",
"de": "Venus"
},
"planet_2": {
"en": "Neptune",
"de": "Neptun"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Uranus",
"de": "Uranus"
},
"planet_2": {
"en": "MC",
"de": "Medium Coeli"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Pluto",
"de": "Pluto"
},
"planet_2": {
"en": "IC",
"de": "Imum Coeli"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mean Node",
"de": "Mittlerer Knoten"
},
"planet_2": {
"en": "True Node",
"de": "Echter Knoten"
},
"aspect": {
"en": "Conjunction"
}
}
]
}
Japanese Response
{
"statusCode": 200,
"output": [
{
"planet_1": {
"en": "Moon",
"ja": "月"
},
"planet_2": {
"en": "Mean Node",
"ja": "平均ノード"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Moon",
"ja": "月"
},
"planet_2": {
"en": "True Node",
"ja": "真ノード"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mercury",
"ja": "水星"
},
"planet_2": {
"en": "Descendant",
"ja": "ディセンダント"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Venus",
"ja": "金星"
},
"planet_2": {
"en": "Neptune",
"ja": "海王星"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Uranus",
"ja": "天王星"
},
"planet_2": {
"en": "MC",
"ja": "天頂"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Pluto",
"ja": "冥王星"
},
"planet_2": {
"en": "IC",
"ja": "天底"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mean Node",
"ja": "平均ノード"
},
"planet_2": {
"en": "True Node",
"ja": "真ノード"
},
"aspect": {
"en": "Conjunction"
}
}
]
}
Polish Response
{
"statusCode": 200,
"output": [
{
"planet_1": {
"en": "Moon",
"pl": "Księżyc"
},
"planet_2": {
"en": "Mean Node",
"pl": "Średni Węzeł"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Moon",
"pl": "Księżyc"
},
"planet_2": {
"en": "True Node",
"pl": "Prawdziwy Węzeł"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mercury",
"pl": "Merkury"
},
"planet_2": {
"en": "Descendant",
"pl": "Descendent"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Venus",
"pl": "Wenus"
},
"planet_2": {
"en": "Neptune",
"pl": "Neptun"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Uranus",
"pl": "Uran"
},
"planet_2": {
"en": "MC",
"pl": "Medium Coeli"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Pluto",
"pl": "Pluton"
},
"planet_2": {
"en": "IC",
"pl": "Imum Coeli"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mean Node",
"pl": "Średni Węzeł"
},
"planet_2": {
"en": "True Node",
"pl": "Prawdziwy Węzeł"
},
"aspect": {
"en": "Conjunction"
}
}
]
}
Turkish Response
{
"statusCode": 200,
"output": [
{
"planet_1": {
"en": "Moon",
"tr": "Ay"
},
"planet_2": {
"en": "Mean Node",
"tr": "Ortalama Düğüm"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Moon",
"tr": "Ay"
},
"planet_2": {
"en": "True Node",
"tr": "Gerçek Düğüm"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mercury",
"tr": "Merkür"
},
"planet_2": {
"en": "Descendant",
"tr": "Alçalan"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Venus",
"tr": "Venüs"
},
"planet_2": {
"en": "Neptune",
"tr": "Neptün"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Uranus",
"tr": "Uranüs"
},
"planet_2": {
"en": "MC",
"tr": "Zirve"
},
"aspect": {
"en": "Conjunction"
}
},
{
"planet_1": {
"en": "Pluto",
"tr": "Plüton"
},
"planet_2": {
"en": "IC",
"tr": "Nadir"
},
"aspect": {
"en": "Trine"
}
},
{
"planet_1": {
"en": "Mean Node",
"tr": "Ortalama Düğüm"
},
"planet_2": {
"en": "True Node",
"tr": "Gerçek Düğüm"
},
"aspect": {
"en": "Conjunction"
}
}
]
}Code Examples
Use the following examples to integrate this API into your application.
PHP Code
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://json.freeastrologyapi.com/western/aspects',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"year": 1998,
"month": 3,
"date": 3,
"hours": 10,
"minutes": 30,
"seconds": 0,
"latitude": 17.38405,
"longitude": 78.45636,
"timezone": 5.5,
"config": {
"observation_point": "topocentric",
"ayanamsha": "tropical",
"language": "en",
"exclude_planets": ["Lilith","Chiron","Ceres","Vesta","Juno","Pallas"],
"allowed_aspects": ["Conjunction","Trine"],
"orb_values":{
"Conjunction": 3,
"Opposition": 5,
"Square": 5,
"Trine": 5,
"Sextile": 5,
"Semi-Sextile": 5,
"Quintile": 5,
"Septile": 5,
"Octile": 5,
"Novile": 5,
"Quincunx": 5,
"Sesquiquadrate": 5
}
}
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'x-api-key: YOUR_API_KEY_HERE'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Python Code
import requests
import json
url = "https://json.freeastrologyapi.com/western/aspects"
payload = json.dumps({
"year": 1998,
"month": 3,
"date": 3,
"hours": 10,
"minutes": 30,
"seconds": 0,
"latitude": 17.38405,
"longitude": 78.45636,
"timezone": 5.5,
"config": {
"observation_point": "topocentric",
"ayanamsha": "tropical",
"language": "en",
"exclude_planets": [
"Lilith",
"Chiron",
"Ceres",
"Vesta",
"Juno",
"Pallas"
],
"allowed_aspects": [
"Conjunction",
"Trine"
],
"orb_values": {
"Conjunction": 3,
"Opposition": 5,
"Square": 5,
"Trine": 5,
"Sextile": 5,
"Semi-Sextile": 5,
"Quintile": 5,
"Septile": 5,
"Octile": 5,
"Novile": 5,
"Quincunx": 5,
"Sesquiquadrate": 5
}
}
})
headers = {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY_HERE'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
Node JS Code
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://json.freeastrologyapi.com/western/aspects',
'headers': {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
"year": 1998,
"month": 3,
"date": 3,
"hours": 10,
"minutes": 30,
"seconds": 0,
"latitude": 17.38405,
"longitude": 78.45636,
"timezone": 5.5,
"config": {
"observation_point": "topocentric",
"ayanamsha": "tropical",
"language": "en",
"exclude_planets": [
"Lilith",
"Chiron",
"Ceres",
"Vesta",
"Juno",
"Pallas"
],
"allowed_aspects": [
"Conjunction",
"Trine"
],
"orb_values": {
"Conjunction": 3,
"Opposition": 5,
"Square": 5,
"Trine": 5,
"Sextile": 5,
"Semi-Sextile": 5,
"Quintile": 5,
"Septile": 5,
"Octile": 5,
"Novile": 5,
"Quincunx": 5,
"Sesquiquadrate": 5
}
}
})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});