Docs › Angles between bodies (aspects, parallels)

Angles between bodies (aspects, parallels)

Aspects (with orb, exactness, applying/separating) for a moment, or for any longitudes you supply.

POST https://astro-agent.dev/v1/western/aspects · $0.02 per call · MCP tool aspects · Try it in the playground

Either give a moment (datetime, optional place) and get the aspects among all planets, or give 'longitudes' {name: degrees} and get the pure geometry. Orbs are explicit and overridable. With options.declination: declinations and the parallels / contra-parallels too.

Authentication

Send your key in the X-Credits-Token header. A free key comes with the Free plan (10,000 calls a month on the core routes, 100 a month on the premium data routes). Without a key, each client gets 1 free call on the $0.01-0.02 routes; past it the API answers 402 with an x402 / MPP pay-per-call offer.

Parameters

ParameterTypeRequiredDefaultDescription
datetimestringLocal civil date-time, ISO 8601: '1990-05-15T14:30' (local clock time at the place) or with an explicit offset '1990-05-15T14:30:00+02:00'. Alternative: 'date' + 'time'.
datestringYYYY-MM-DD (use with 'time' instead of 'datetime').
timestringHH:MM or HH:MM:SS, 24 h. Omit if unknown (computed at 12:00 with a TIME_UNKNOWN warning).
latitudenumberDecimal degrees, north positive.
longitudenumberDecimal degrees, east positive.
timezonestringIANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date.
time_basisstring: civil | utc | lmt | true_solar"civil"What the given clock time is: civil wall-clock (default), UTC, Local Mean Time, or true (apparent) solar time.
ambiguous_timestring: earlier | later"earlier"Which occurrence to use when a local time happens twice (DST fall-back).
longitudesobjectOptional {name: degrees} or {name: {longitude, speed, declination?, declination_speed?}}; when given, no ephemeris is used.
optionsobjectOptional calculation settings; every default is the common Western convention.
options.house_systemstring: alcabitius | campanus | equal | koch | meridian | morinus | placidus | porphyry | regiomontanus | topocentric | whole_sign"placidus"House system for cusps and planet houses, e.g. 'placidus' (default) or 'whole_sign'.
options.zodiacstring: tropical | sidereal"tropical"'tropical' (Western, default) or 'sidereal' (pair it with 'ayanamsa').
options.ayanamsastring: fagan_bradley | krishnamurti | lahiri | raman | true_chitrapaksha | yukteshwar"lahiri"Only with zodiac=sidereal.
options.pointsvalue'all' or a list from ['sun', 'moon', 'mercury', 'venus', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune', 'pluto', 'mean_node', 'true_node', 'mean_lilith']. Default: 10 planets + true node + mean Lilith.
options.aspectsvalue'all' or a list from ['conjunction', 'opposition', 'trine', 'square', 'sextile', 'quincunx', 'semisextile', 'semisquare', 'sesquiquadrate', 'quintile', 'biquintile']. Default: the 5 majors.
options.orbsobjectOverride orbs per aspect, degrees.
options.luminary_orb_bonusnumber2Extra orb in degrees for aspects involving the Sun or the Moon. Example: 2.
options.declinationbooleanfalseAlso return the declinations and the parallels / contra-parallels between points.
options.declination_orbnumber1Orb for parallels and contra-parallels, degrees. Example: 1.

Example request

curl

curl -s https://astro-agent.dev/v1/western/aspects \
  -H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datetime": "2026-10-01T12:00:00Z"}'

Python

import os
import requests

body = {'datetime': '2026-10-01T12:00:00Z'}
r = requests.post("https://astro-agent.dev/v1/western/aspects", json=body,
                  headers={"X-Credits-Token": os.environ.get("ASTRO_AGENTS_KEY", "")}, timeout=60)
if not r.ok:
    raise SystemExit(f"{r.status_code}: {r.text}")
data = r.json()

for a in data["result"]["aspects"]:
    print(a["point_a"], a["aspect"], a["point_b"], f'orb {a["orb"]} deg')
print("result_sha256:", data["meta"]["result_sha256"])

JavaScript (Node 18+)

// Node 18+ (built-in fetch). Save as call.mjs and run: node call.mjs
const body = {"datetime": "2026-10-01T12:00:00Z"};
const res = await fetch("https://astro-agent.dev/v1/western/aspects", {
  method: "POST",
  headers: {"X-Credits-Token": process.env.ASTRO_AGENTS_KEY ?? "", "Content-Type": "application/json"},
  body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const data = await res.json();

for (const a of data.result.aspects)
  console.log(a.point_a, a.aspect, a.point_b, `orb ${a.orb} deg`);
console.log("result_sha256:", data.meta.result_sha256);

Example response

A real response to the request above (lists shortened to 3 items). The same request always returns this result_sha256:

0bddbfc9d2343055cd651f50b7df0660520e47147a0db6ca097449e930b782a7

{
  "endpoint": "western/aspects",
  "result": {
    "subject": {
      "time": {
        "local_input": "2026-10-01T12:00:00Z",
        "time_basis": "civil",
        "timezone": null,
        "timezone_source": "offset_in_datetime",
        "utc_offset": "+00:00",
        "is_dst": null,
        "utc": "2026-10-01T12:00:00Z",
        "julian_day_ut": 2461315.000001,
        "julian_day_tt": 2461315.000801,
        "delta_t_seconds": 69.091,
        "time_known": true
      }
    },
    "settings": {
      "zodiac": "tropical",
      "aspects": {
        "types": [
          "conjunction",
          "opposition",
          "trine"
        ],
        "orbs": {
          "conjunction": 8.0,
          "opposition": 8.0,
          "trine": 7.0,
          "square": 7.0,
          "sextile": 5.0
        },
        "luminary_orb_bonus": 2.0
      }
    },
    "aspects": [
      {
        "point_a": "neptune",
        "point_b": "pluto",
        "aspect": "sextile",
        "angle": 60.0,
        "orb": 0.270713,
        "orb_allowed": 5.0,
        "exactness_pct": 94.6,
        "state": "separating"
      },
      {
        "point_a": "mercury",
        "point_b": "mean_lilith",
        "aspect": "sextile",
        "angle": 60.0,
        "orb": 0.428251,
        "orb_allowed": 5.0,
        "exactness_pct": 91.4,
        "state": "applying"
      },
      {
        "point_a": "moon",
        "point_b": "saturn",
        "aspect": "sextile",
        "angle": 60.0,
        "orb": 0.490967,
        "orb_allowed": 7.0,
        "exactness_pct": 93.0,
        "state": "applying"
      }
    ]
  },
  "meta": {
    "engine": "astro-agents/1.9.0",
    "ephemeris": "NASA/JPL DE440 (1800-01-01..2200-01-01)",
    "astronomy_library": "skyfield/1.55",
    "frame": "geocentric apparent positions, true ecliptic and equinox of date (IAU 2006/2000A)",
    "deterministic": true,
    "llm_used": false,
    "input_sha256": "f7faf127bc97341b8d0b04d605c62df80f69847569b01321e84f6af72570bb50",
    "result_sha256": "0bddbfc9d2343055cd651f50b7df0660520e47147a0db6ca097449e930b782a7",
    "reproducibility": "result_sha256 = SHA-256 of the result serialized as JSON with sorted keys, no whitespace, UTF-8, floats rounded to 6 decimals. Same input + same engine version => same hash."
  }
}

Response fields

FieldTypeDescription
result.settingsobjectThe aspect set and orbs applied, and where the longitudes came from.
result.aspectsarrayAspects between two points: point_a, point_b, aspect name, exact angle, orb, allowed orb, exactness percentage and whether it is applying or separating.
result.declinationsobjectWith options.declination: the declination of each point, degrees.
result.declination_aspectsarrayWith options.declination: parallels and contra-parallels (point_a, point_b, aspect, both declinations, orb, allowed orb, applying or separating).
endpointstringThe route that computed it.
meta.input_sha256stringSHA-256 of the canonical request.
meta.result_sha256stringSHA-256 of the canonical result: POST /v1/verify recomputes it.
meta.engine_version / meta.ephemerisstringEngine release and ephemeris (NASA/JPL DE440).

Errors

400 for an invalid input (never charged), 401 / 403 for a key problem, 402 to pay, 429 for a quota or rate limit: see the error reference.