Astrology Aspects API

AstroAPI uses Western (tropical), geocentric astrology by default. Sidereal or Vedic-style calculations are not applied unless explicitly enabled and documented.

Calculate angular relationships between planets in a natal chart. Aspect results are derived from the underlying chart calculation data and returned as raw values.

Endpoint

POST https://api.astroapi.io/api/astro/aspects

Include Authorization: Bearer <API_KEY>.

Example Request

{
  "birth": {
    "date": "1990-01-01",
    "time": "12:00",
    "timezone": "UTC",
    "lat": 40.7128,
    "lon": -74.0060
  }
}

Example Response

For backward compatibility, the aspects property contains the full calculated chart; the aspect array is response.aspects.aspects. This verified example is abbreviated and numerically rounded.

{
  "type": "aspects",
  "input": {
    "birth": {
      "date": "1990-01-01",
      "time": "12:00",
      "timezone": "UTC",
      "lat": 40.7128,
      "lon": -74.0060
    }
  },
  "aspects": {
    "planets": {
      "Sun": { "lon": 280.8143, "sign": "Capricorn" },
      "Mars": { "lon": 250.0001, "sign": "Sagittarius" }
    },
    "houses": {
      "ascendant": 274.6427,
      "mc": 208.9108,
      "systems": {
        "whole_sign": { "houses": { "1": 270, "2": 300 } },
        "equal": { "houses": { "1": 274.6427, "2": 304.6427 } }
      }
    },
    "aspects": [
      { "p1": "Sun", "p2": "Mars", "type": "semisextile", "exact_angle": 30, "distance": 30.8142, "orb": 0.8142 }
    ],
    "nodes": { "mean": { "longitude": 318.4317, "sign": "Aquarius", "deg_in_sign": 18.4317 } },
    "metadata": { "note": "Geocentric positions using JPL DE421 ephemeris." }
  }
}

Quick Test / curl

Use this curl command from a trusted server to test the Aspects endpoint:

curl -i https://api.astroapi.io/api/astro/aspects \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ASTROAPI_KEY}" \
  -d '{
    "birth": {
      "date": "2000-01-01",
      "time": "12:00",
      "timezone": "America/New_York",
      "lat": 33.7488,
      "lon": -84.3877
    }
  }'

Common Uses

• Natal chart analysis
• Aspect line or table rendering
• Astrology research tools
• Client-side interpretation systems

Aspect definitions

The engine uses one symmetric maximum orb per aspect: conjunction and opposition 8°, trine 7°, square 6°, sextile 5°, semisextile/semisquare/sesquiquadrate 3°, and quintile/biquintile 2.5°. A planet pair is returned at most once, using the first matching definition in that order.

Public chart dates must fall between 1900-01-01 and 2050-12-31. Omitted birth timezones default to UTC.

This API does not perform interpretation, scoring, or compatibility analysis. These responsibilities are handled by the client application.

// Node.js 22+ — server-side only
fetch("https://api.astroapi.io/api/astro/aspects", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.ASTROAPI_KEY}`
  },
  body: JSON.stringify({
    birth: {
      date: "1990-01-01",
      time: "12:00",
      timezone: "America/New_York",
      lat: 40.7128,
      lon: -74.0060
    }
  })
})
  .then(res => res.json())
  .then(data => console.log(data));

# Python — Aspects API
import os
import requests

url = "https://api.astroapi.io/api/astro/aspects"

payload = {
  "birth": {
    "date": "1990-01-01",
    "time": "12:00",
    "timezone": "America/New_York",
    "lat": 40.7128,
    "lon": -74.0060
  }
}

headers = {
  "Content-Type": "application/json",
  "Authorization": f"Bearer {os.environ['ASTROAPI_KEY']}"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())