Docs › Planetary positions for any date (ephemeris)

Planetary positions for any date (ephemeris)

Planetary positions for any date and time (ephemeris): tropical or sidereal longitude, latitude, speed and retrograde flag of the Sun, Moon, Mercury..Pluto, nodes and Lilith.

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

Geocentric apparent positions from NASA/JPL DE440 for any moment 1800-2200, with sign, degree, element, modality, daily speed and retrograde status. Location is optional (only used to interpret a local time). Options: perspective 'heliocentric' (seen from the Sun) and coordinates 'equatorial' (right ascension, declination, out-of-bounds).

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).
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.perspectivestring: geocentric | heliocentric"geocentric"'geocentric' (default) or 'heliocentric' (geometric, seen from the Sun: Earth instead of Sun and Moon, no lunar points).
options.coordinatesstring: ecliptic | equatorial"ecliptic"'ecliptic' (default: longitude/latitude) or 'equatorial': also each point's right ascension, declination, their daily speeds and an out-of-bounds flag.

Example request

curl

curl -s https://astro-agent.dev/v1/western/positions \
  -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/positions", 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 p in data["result"]["points"]:
    print(f'{p["name"]:<10} {p["longitude"]:9.4f} deg  speed {p["speed_longitude"]:+.4f} deg/day  '
          f'retrograde={p["retrograde"]}')
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/positions", {
  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 p of data.result.points)
  console.log(p.name.padEnd(10), p.longitude.toFixed(4), "deg", p.retrograde ? "retrograde" : "");
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:

269109e17efc86d60897373ac8244ecff90f9c71f9dd1836d848fddba92fcae1

{
  "endpoint": "western/positions",
  "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"
    },
    "points": [
      {
        "point": "sun",
        "name": "Sun",
        "longitude": 188.33017,
        "sign": "Libra",
        "sign_index": 6,
        "degree_in_sign": 8.33017,
        "position": "8°19'49\" Libra",
        "element": "air",
        "modality": "cardinal",
        "latitude": 0.000187,
        "speed_longitude": 0.982927,
        "retrograde": false,
        "distance_au": 1.001186
      },
      {
        "point": "moon",
        "name": "Moon",
        "longitude": 71.048302,
        "sign": "Gemini",
        "sign_index": 2,
        "degree_in_sign": 11.048302,
        "position": "11°02'54\" Gemini",
        "element": "air",
        "modality": "mutable",
        "latitude": 5.056642,
        "speed_longitude": 14.283559,
        "retrograde": false,
        "distance_au": 0.002469
      },
      {
        "point": "mercury",
        "name": "Mercury",
        "longitude": 211.339088,
        "sign": "Scorpio",
        "sign_index": 7,
        "degree_in_sign": 1.339088,
        "position": "1°20'21\" Scorpio",
        "element": "water",
        "modality": "fixed",
        "latitude": -1.80707,
        "speed_longitude": 1.313986,
        "retrograde": false,
        "distance_au": 1.169303
      }
    ]
  },
  "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": "34b719359ced9d2d01130742d40810c8dcebdc0abf6c11e22e9161b55c3cd5f6",
    "result_sha256": "269109e17efc86d60897373ac8244ecff90f9c71f9dd1836d848fddba92fcae1",
    "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.subjectobjectThe resolved input: 'time' (local input, time zone and historical UTC offset, UT, Julian days, Delta T) and, when given, 'location' (latitude, longitude).
result.settingsobjectSettings applied (zodiac).
result.pointsarrayOne entry per body or point (Sun to Pluto, lunar nodes, Chiron...): ecliptic longitude, sign, degree in sign, element, modality, latitude, daily speed, retrograde flag, distance in AU and, with a location, the house.
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.