Docs › Angular separations between bodies

Angular separations between bodies

Pairs of bodies whose ecliptic separation is within a tolerance of 0, 60, 90, 120 or 180 degrees (or any angle you choose), with the deviation; optionally equal and opposite declinations.

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

For a moment (computed from DE440) or for longitudes you supply: every pair of bodies at a chosen separation angle, with its deviation from the exact angle, the tolerance applied, and whether the bodies are approaching or receding from it. Option 'declination': pairs with equal or opposite declinations.

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 {body: degrees} or {body: {longitude, speed, declination?, declination_speed?}}; when given, no ephemeris is used.
optionsobjectOptional.
options.bodiesvalue'all' or a list from ['sun', 'moon', 'mercury', 'venus', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune', 'pluto', 'lunar_node_true', 'lunar_node_true_descending', 'lunar_node_mean', 'lunar_apogee_mean']. Default: the Sun, the Moon, Mercury..Pluto, the Moon's true ascending node, its descending node and its mean apogee.
options.anglesvalueSeparation angles in degrees, 'all' or a list from [0, 30, 45, 60, 72, 90, 120, 135, 144, 150, 180]. Default: [0, 60, 90, 120, 180].
options.tolerancesobjectTolerance in degrees per angle, e.g. {"90": 6}. Defaults: 0 and 180: 8; 90 and 120: 7; 60: 5; the others: 2.
options.sun_moon_tolerance_bonusnumber2Extra tolerance in degrees when either body is the Sun or the Moon.
options.declinationbooleanfalseAlso return the declinations and the pairs with equal or opposite declinations.
options.declination_tolerancenumber1Tolerance in degrees for equal / opposite declinations.

Example request

curl

curl -s https://astro-agent.dev/v1/astronomy/angles \
  -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/astronomy/angles", 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"]["separations"]:
    print(a["point_a"], a["point_b"], a["angle"], "deg, deviation", a["deviation"], "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/astronomy/angles", {
  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.separations)
  console.log(a.point_a, a.point_b, a.angle, "deg, deviation", a.deviation, "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:

bf626bd75b094bce51906ce374f5193169e6525457c2cca5b13dc6c51350fc5a

{
  "endpoint": "astronomy/angles",
  "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
      }
    },
    "separations": [
      {
        "point_a": "neptune",
        "point_b": "pluto",
        "angle": 60,
        "deviation": 0.270713,
        "tolerance": 5.0,
        "exactness_pct": 94.6,
        "state": "receding"
      },
      {
        "point_a": "mercury",
        "point_b": "lunar_apogee_mean",
        "angle": 60,
        "deviation": 0.428251,
        "tolerance": 5.0,
        "exactness_pct": 91.4,
        "state": "approaching"
      },
      {
        "point_a": "moon",
        "point_b": "saturn",
        "angle": 60,
        "deviation": 0.490967,
        "tolerance": 7.0,
        "exactness_pct": 93.0,
        "state": "approaching"
      }
    ],
    "settings": {
      "separations": {
        "angles": [
          0,
          60,
          90
        ],
        "tolerances": {
          "0": 8.0,
          "180": 8.0,
          "120": 7.0,
          "90": 7.0,
          "60": 5.0
        },
        "sun_moon_tolerance_bonus": 2.0,
        "rule": "a pair is listed when |separation - angle| <= tolerance (plus the Sun/Moon bonus when either body is the Sun or the Moon); deviation = |separation - angle|"
      },
      "longitude_reference": "ecliptic longitude from the true equinox of date (0-360 degrees)"
    }
  },
  "meta": {
    "engine": "astro-agents/1.10.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": "685f7425a236aeb1cbac66e5e9652d3cad91a42a172111ba743f3c92b8bb493b",
    "result_sha256": "bf626bd75b094bce51906ce374f5193169e6525457c2cca5b13dc6c51350fc5a",
    "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 separation angles and tolerances applied, the rule, and where the longitudes came from.
result.separationsarrayPairs at a separation angle: point_a, point_b, angle (degrees), deviation from it, tolerance, exactness percentage, approaching or receding.
result.declinationsobjectWith options.declination: the declination of each body, degrees.
result.declination_relationsarrayWith options.declination: pairs with equal or opposite declinations (relation, both declinations, deviation, tolerance).
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).

CSV

Add ?format=csv to get the table of the result as CSV (gzip when your client sends Accept-Encoding: gzip): POST https://astro-agent.dev/v1/astronomy/angles?format=csv. Same price and quota as JSON; the X-Result-SHA256 header is the hash of the JSON result the CSV is a view of. Long ranges in one file: bulk export.

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.