Docs › The sky now: positions, Moon phase, next events
The sky now: positions, Moon phase, next events
The sky at a moment: planetary positions, which planets are retrograde, the Moon's phase and illumination, and the exact times of the next stations, lunations and separations.
POST https://astro-agent.dev/v1/astronomy/sky · $0.01 per call · MCP tool sky_now
· Try it in the playground
One call for 'what is happening in the sky': positions, retrograde planets, the Moon's phase, and the events of the next days (1-90): stations, lunations, separations of 0, 60, 90, 120 and 180 degrees, and ecliptic longitudes crossing multiples of 30 degrees, each to the minute (UTC).
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). | |
days | integer | 30 | How many days ahead to list events. Example: 30. |
Example request
curl
curl -s https://astro-agent.dev/v1/astronomy/sky \
-H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
-H "Content-Type: application/json" \
-d '{"datetime": "2026-10-01T00:00Z", "days": 30}'Python
import os
import requests
body = {'datetime': '2026-10-01T00:00Z', 'days': 30}
r = requests.post("https://astro-agent.dev/v1/astronomy/sky", 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()
moon = data["result"]["now"]["moon"]
print("Moon:", moon["phase"], f'{moon["illumination"]:.0%} lit')
for ev in data["result"]["events"]:
what = ev.get("kind") or ev.get("body") or ev.get("phase") or "-".join(ev.get("bodies", []))
detail = ev.get("eclipse_type") or ev.get("turns") or ev.get("angle") or ev.get("relation") or ""
print(ev["exact_utc"], ev["type"], what, detail)
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-01T00:00Z", "days": 30};
const res = await fetch("https://astro-agent.dev/v1/astronomy/sky", {
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();
const moon = data.result.now.moon;
console.log("Moon:", moon.phase, Math.round(moon.illumination * 100) + "% lit");
for (const ev of data.result.events) {
const what = ev.kind || ev.body || ev.phase || (ev.bodies || []).join("-");
console.log(ev.exact_utc, ev.type, what, ev.eclipse_type || ev.turns || ev.angle || ev.relation || "");
}
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:
a6d558a4600aba4652107dc8af5df85b0c1a24fd5dee7055ea50e557fc560f60
{
"endpoint": "astronomy/sky",
"result": {
"subject": {
"time": {
"local_input": "2026-10-01T00:00Z",
"time_basis": "civil",
"timezone": null,
"timezone_source": "offset_in_datetime",
"utc_offset": "+00:00",
"is_dst": null,
"utc": "2026-10-01T00:00:00Z",
"julian_day_ut": 2461314.500001,
"julian_day_tt": 2461314.500801,
"delta_t_seconds": 69.091,
"time_known": true
}
},
"now": {
"points": [
{
"point": "sun",
"name": "Sun",
"longitude": 187.838755,
"latitude": 0.000189,
"speed_longitude": 0.982609,
"retrograde": false,
"distance_au": 1.001326
},
{
"point": "moon",
"name": "Moon",
"longitude": 63.906575,
"latitude": 5.149558,
"speed_longitude": 14.282884,
"retrograde": false,
"distance_au": 0.00247
},
{
"point": "mercury",
"name": "Mercury",
"longitude": 210.679372,
"latitude": -1.747686,
"speed_longitude": 1.324494,
"retrograde": false,
"distance_au": 1.175837
}
],
"retrograde": [
"saturn",
"uranus",
"neptune"
],
"moon": {
"elongation_deg": 236.06782,
"phase": "waning gibbous",
"illumination": 0.77887,
"waxing": false
}
},
"events": [
{
"type": "separation",
"bodies": [
"mercury",
"mars"
],
"exact_utc": "2026-10-02T09:14Z",
"angle": 90
},
{
"type": "separation",
"bodies": [
"mercury",
"pluto"
],
"exact_utc": "2026-10-02T20:43Z",
"angle": 90
},
{
"type": "separation",
"bodies": [
"mars",
"neptune"
],
"exact_utc": "2026-10-02T22:18Z",
"angle": 120
}
],
"counts": {
"longitude_crossing": 2,
"station": 3,
"lunation": 4,
"separation": 14
},
"settings": {
"days": 30,
"event_bodies": [
"sun",
"mercury",
"venus"
],
"separation_angles": [
0,
60,
90
],
"precision": "event times +/- 1 minute (UTC); stations and slow declination crossings are flat, so their minute is the least sharp",
"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": "c1fc8ece368980d8de5fa8d78c4c26caa0daacb9220761c6bce3eab0ef4f415c",
"result_sha256": "a6d558a4600aba4652107dc8af5df85b0c1a24fd5dee7055ea50e557fc560f60",
"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: days ahead, the bodies, the separation angles searched, the longitude reference and the precision of event times. |
result.now | object | The sky at the moment: 'points' (positions, speeds, retrograde flags), 'retrograde' (bodies retrograde now) and 'moon' (elongation, phase name, illumination, waxing). |
result.events | array | Events in time order, each with 'type' (eclipse, lunation, station, separation, longitude_crossing, declination, declination_beyond_obliquity), its details, 'exact_utc'. |
result.counts | object | Number of events of each type. |
result.warnings | array | Notes on the input or the calculation (for example an assumed local noon when only a date is given). Present only when there is something to say. |
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/sky?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.