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
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
datetime | string | | Local 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'. | |
date | string | | YYYY-MM-DD (use with 'time' instead of 'datetime'). | |
time | string | | HH:MM or HH:MM:SS, 24 h. Omit if unknown (computed at 12:00 with a TIME_UNKNOWN warning). | |
latitude | number | | Decimal degrees, north positive. | |
longitude | number | | Decimal degrees, east positive. | |
timezone | string | | IANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date. | |
time_basis | string: 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_time | string: earlier | later | "earlier" | Which occurrence to use when a local time happens twice (DST fall-back). | |
options | object | | Optional calculation settings; every default is the common Western convention. | |
options.house_system | string: 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.zodiac | string: tropical | sidereal | "tropical" | 'tropical' (Western, default) or 'sidereal' (pair it with 'ayanamsa'). | |
options.ayanamsa | string: fagan_bradley | krishnamurti | lahiri | raman | true_chitrapaksha | yukteshwar | "lahiri" | Only with zodiac=sidereal. | |
options.points | value | | '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.aspects | value | | 'all' or a list from ['conjunction', 'opposition', 'trine', 'square', 'sextile', 'quincunx', 'semisextile', 'semisquare', 'sesquiquadrate', 'quintile', 'biquintile']. Default: the 5 majors. | |
options.orbs | object | | Override orbs per aspect, degrees. | |
options.luminary_orb_bonus | number | 2 | Extra orb in degrees for aspects involving the Sun or the Moon. Example: 2. | |
options.perspective | string: geocentric | heliocentric | "geocentric" | 'geocentric' (default) or 'heliocentric' (geometric, seen from the Sun: Earth instead of Sun and Moon, no lunar points). | |
options.coordinates | string: 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
| Field | Type | Description |
|---|---|---|
result.subject | object | The resolved input: 'time' (local input, time zone and historical UTC offset, UT, Julian days, Delta T) and, when given, 'location' (latitude, longitude). |
result.settings | object | Settings applied (zodiac). |
result.points | array | One 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. |
endpoint | string | The route that computed it. |
meta.input_sha256 | string | SHA-256 of the canonical request. |
meta.result_sha256 | string | SHA-256 of the canonical result: POST /v1/verify recomputes it. |
meta.engine_version / meta.ephemeris | string | Engine 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.