Docs › Planetary phenomena: oppositions, conjunctions, elongations

Planetary phenomena: oppositions, conjunctions, elongations

Every conjunction with the Sun (inferior / superior for Mercury and Venus), opposition, greatest elongation, conjunction between two planets, perihelion and aphelion between two dates, to the second.

POST https://astro-agent.dev/v1/astronomy/phenomena · $0.10 per call · MCP tool planetary_phenomena · Try it in the playground

For almanacs, observing guides and astronomy newsletters: between two dates (up to 366 days, 1800-2199), each planet's conjunctions with the Sun, oppositions (with the Earth distance), greatest elongations east or west (with the angle), conjunctions between planets (with their angular separation and distance from the Sun), and perihelion and aphelion (heliocentric distance), each with a stable key. Matches the published 2026 dates.

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
startstringyesFirst UTC date, YYYY-MM-DD (1800-01-08..2199-12-30).
endstringyesLast UTC date, YYYY-MM-DD, at most 366 days after start.
bodiesarray of string (mercury, venus, mars, jupiter, saturn, uranus, neptune)Planets to follow. Default: Mercury..Neptune.
includearray of string (conjunction, opposition, greatest_elongation, planet_conjunction, perihelion, aphelion)Phenomena to return. Default: all.

Example request

curl

curl -s https://astro-agent.dev/v1/astronomy/phenomena \
  -H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start": "2026-01-01", "end": "2026-12-31", "include": ["opposition", "greatest_elongation"]}'

Python

import os
import requests

body = {'start': '2026-01-01', 'end': '2026-12-31', 'include': ['opposition', 'greatest_elongation']}
r = requests.post("https://astro-agent.dev/v1/astronomy/phenomena", 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 e in data["result"]["events"]:
    who = e.get("body") or "-".join(e["bodies"])
    print(e["utc"], e["type"], who, e.get("direction", ""), e.get("elongation_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 = {"start": "2026-01-01", "end": "2026-12-31", "include": ["opposition", "greatest_elongation"]};
const res = await fetch("https://astro-agent.dev/v1/astronomy/phenomena", {
  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 e of data.result.events)
  console.log(e.utc, e.type, e.body || e.bodies.join("-"), e.direction || "", e.elongation_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:

e66c72821a02cdfa7023627c8ff764724cf411b756680074219cb9665fc37a3d

{
  "endpoint": "astronomy/phenomena",
  "result": {
    "settings": {
      "start": "2026-01-01",
      "end": "2026-12-31",
      "bodies": [
        "mercury",
        "venus",
        "mars"
      ],
      "include": [
        "opposition",
        "greatest_elongation"
      ],
      "conventions": {
        "frame": "geocentric apparent positions, true ecliptic and equinox of date (NASA/JPL DE440)",
        "conjunction": "the planet's ecliptic longitude equals the Sun's; Mercury and Venus: inferior (nearer than the Sun) or superior",
        "opposition": "the planet's ecliptic longitude differs from the Sun's by 180 deg (Mars..Neptune)",
        "greatest_elongation": "maximum of the planet-Sun angular separation (Mercury, Venus): east = evening sky, west = morning sky",
        "planet_conjunction": "equal geocentric ecliptic longitudes of two planets, with their angular separation then",
        "perihelion_aphelion": "minimum / maximum of the planet's heliocentric distance",
        "times": "UTC, refined to under a second, given to the second"
      }
    },
    "events": [
      {
        "type": "opposition",
        "utc": "2026-01-10T08:42:09Z",
        "timestamp": 1768034529,
        "body": "jupiter",
        "distance_au": 4.231852,
        "key": "opposition:jupiter:2026-01-10T08:42Z"
      },
      {
        "type": "greatest_elongation",
        "utc": "2026-02-19T17:41:09Z",
        "timestamp": 1771522869,
        "body": "mercury",
        "direction": "east",
        "elongation_deg": 18.1227,
        "key": "greatest_elongation:mercury:2026-02-19T17:41Z"
      },
      {
        "type": "greatest_elongation",
        "utc": "2026-04-03T22:33:35Z",
        "timestamp": 1775255615,
        "body": "mercury",
        "direction": "west",
        "elongation_deg": 27.8195,
        "key": "greatest_elongation:mercury:2026-04-03T22:33Z"
      }
    ],
    "counts": {
      "opposition": 4,
      "greatest_elongation": 7
    }
  },
  "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": "41b16523604c14462c266c2822441e4b949f25eb43bfe510a734007d63795dab",
    "result_sha256": "e66c72821a02cdfa7023627c8ff764724cf411b756680074219cb9665fc37a3d",
    "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.settingsobjectstart, end, bodies, include and every convention.
result.eventsarrayIn time order: {type, utc, timestamp, key, body | bodies, and per type: kind (inferior / superior), separation_from_sun_deg, distance_au, direction (east / west), elongation_deg, separation_deg, elongation_from_sun_deg, heliocentric_distance_au}.
result.countsobjectNumber of events per type.
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/phenomena?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.