Docs › Planetary positions for any date (ephemeris)
Planetary positions for any date (ephemeris)
Ecliptic longitude and latitude, daily speed, retrograde flag and distance of the Sun, the Moon, Mercury..Pluto and the lunar nodes, for any moment 1800-2200.
POST https://astro-agent.dev/v1/astronomy/positions · $0.01 per call · MCP tool body_positions
· Try it in the playground
Geocentric apparent positions from NASA/JPL DE440 (true ecliptic and equinox of date, IAU 2006/2000A), with the Moon's ascending and descending nodes and its mean apogee. Location is optional (only used to interpret a local time). Options: 'heliocentric' perspective (seen from the Sun) and 'equatorial' coordinates (right ascension, declination, and whether |declination| exceeds the obliquity).
Authentication
Send your key in the X-Credits-Token header. A free key comes with the Free plan (1,000 calls a month, up to 100 of them 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. | |
options.bodies | value | | '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.perspective | string: geocentric | heliocentric | "geocentric" | 'geocentric' (default) or 'heliocentric' (geometric, seen from the Sun: the Earth instead of the Sun and the Moon, no lunar points). | |
options.coordinates | string: ecliptic | equatorial | "ecliptic" | 'ecliptic' (default: longitude/latitude) or 'equatorial': also each body's right ascension, declination, their daily speeds and whether |declination| exceeds the obliquity of the ecliptic. |
Example request
curl
curl -s https://astro-agent.dev/v1/astronomy/positions \
-H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
-H "Content-Type: application/json" \
-d '{"datetime": "2026-12-21T12:00:00Z"}'Python
import os
import requests
body = {'datetime': '2026-12-21T12:00:00Z'}
r = requests.post("https://astro-agent.dev/v1/astronomy/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-12-21T12:00:00Z"};
const res = await fetch("https://astro-agent.dev/v1/astronomy/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:
37e1d0fd3a87aa9cf7fbdbe2c1999b8e60cab818f687db06979f48055ae2d7f8
{
"endpoint": "astronomy/positions",
"result": {
"subject": {
"time": {
"local_input": "2026-12-21T12:00:00Z",
"time_basis": "civil",
"timezone": null,
"timezone_source": "offset_in_datetime",
"utc_offset": "+00:00",
"is_dst": null,
"utc": "2026-12-21T12:00:00Z",
"julian_day_ut": 2461396.000001,
"julian_day_tt": 2461396.000801,
"delta_t_seconds": 69.096,
"time_known": true
}
},
"settings": {
"longitude_reference": "ecliptic longitude from the true equinox of date (0-360 degrees)"
},
"points": [
{
"point": "sun",
"name": "Sun",
"longitude": 269.625158,
"latitude": 0.000224,
"speed_longitude": 1.01789,
"retrograde": false,
"distance_au": 0.983758
},
{
"point": "moon",
"name": "Moon",
"longitude": 53.559896,
"latitude": 5.106911,
"speed_longitude": 14.697656,
"retrograde": false,
"distance_au": 0.002436
},
{
"point": "mercury",
"name": "Mercury",
"longitude": 263.315436,
"latitude": -0.82875,
"speed_longitude": 1.560208,
"retrograde": false,
"distance_au": 1.430316
}
]
},
"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": "15807a6c9f1d71a20756c90d26bf3bfa5ab2c020e1d6bc75496bdbcaab68880b",
"result_sha256": "37e1d0fd3a87aa9cf7fbdbe2c1999b8e60cab818f687db06979f48055ae2d7f8",
"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: the longitude reference (true equinox of date), perspective, coordinates. |
result.points | array | One entry per body (Sun to Pluto, the Moon's ascending and descending nodes, its mean apogee): ecliptic longitude and latitude, daily speed, retrograde flag, distance in AU; with equatorial coordinates, right ascension, declination and whether |declination| exceeds the obliquity. |
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). |
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/positions?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.