Docs › Astronomical summary of the day for a place
Astronomical summary of the day for a place
One call for a day at a place: sunrise, sunset, twilight, day length, golden and blue hour; the Moon's phase, illumination, rise and set; the planets observable that night; the next lunations, planetary stations and eclipse.
POST https://astro-agent.dev/v1/astronomy/day · $0.02 per call · MCP tool day_summary
· Try it in the playground
The daily sky block of a weather, calendar or outdoor app, in one request: the Sun (rise, solar noon, set, civil / nautical / astronomical dawn and dusk, day length, golden and blue hour), the Moon (phase, illuminated fraction, age, distance, moonrise, transit, moonset, the next principal phase), the planets observable that night (window, best time, altitude, azimuth, magnitude; brightest first), the lunations and planetary stations of the next 7 days, and the next solar or lunar eclipse anywhere on Earth. Local times with offset, UTC and unix timestamps; each block follows the conventions of its own route.
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 |
|---|---|---|---|---|
date | string | yes | | The local calendar day at the place, YYYY-MM-DD (1800-01-02..2199-12-30). |
latitude | number | yes | | Decimal degrees, north positive. |
longitude | number | yes | | Decimal degrees, east positive. |
elevation_m | number | 0 | Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled). | |
timezone | string | | IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules). |
Example request
curl
curl -s https://astro-agent.dev/v1/astronomy/day \
-H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
-H "Content-Type: application/json" \
-d '{"date": "2026-08-10", "latitude": 48.8566, "longitude": 2.3522}'Python
import os
import requests
body = {'date': '2026-08-10', 'latitude': 48.8566, 'longitude': 2.3522}
r = requests.post("https://astro-agent.dev/v1/astronomy/day", 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()
r = data["result"]
print("Sunrise", r["sun"]["sunrise"]["local"], " Sunset", r["sun"]["sunset"]["local"])
print("Moon:", r["moon"]["name"], f'{r["moon"]["illuminated_fraction"]:.0%} lit')
for p in r["planets_tonight"]:
print("Tonight:", p["body"], "best at", p["best"]["local"][11:16], "alt", p["best"]["altitude"])
if r["next_eclipse"]:
print("Next eclipse:", r["next_eclipse"]["kind"], r["next_eclipse"]["eclipse_type"], r["next_eclipse"]["utc"])
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 = {"date": "2026-08-10", "latitude": 48.8566, "longitude": 2.3522};
const res = await fetch("https://astro-agent.dev/v1/astronomy/day", {
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 r = data.result;
console.log("Sunrise", r.sun.sunrise.local, " Sunset", r.sun.sunset.local);
console.log("Moon:", r.moon.name, Math.round(r.moon.illuminated_fraction * 100) + "% lit");
for (const p of r.planets_tonight) console.log("Tonight:", p.body, "best at", p.best.local.slice(11, 16));
if (r.next_eclipse) console.log("Next eclipse:", r.next_eclipse.kind, r.next_eclipse.eclipse_type, r.next_eclipse.utc);
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:
9a5885bae51d624822ffd64c7d6d49a2d0132ae4d25074c20ef60f149c3a8e07
{
"endpoint": "astronomy/day",
"result": {
"subject": {
"location": {
"latitude": 48.8566,
"longitude": 2.3522,
"elevation_m": 0.0
},
"timezone": "Europe/Paris",
"timezone_source": "resolved_from_coordinates",
"date": "2026-08-10",
"window_utc": {
"start": "2026-08-09T22:00:00Z",
"end": "2026-08-10T22:00:00Z"
}
},
"settings": {
"conventions": {
"sun": "astronomy/rise-set conventions (upper limb, 34' refraction; twilight at -6/-12/-18 deg)",
"moon": "astronomy/moon at local noon; moonrise/transit/moonset for the local day",
"planets_tonight": "astronomy/visibility defaults: altitude >= 10 deg while the Sun is <= -6 deg, the longest-elevated window of each planet, brightest first",
"next_events": "lunations and planetary stations of the next 7 days (geocentric, to the minute)",
"next_eclipse": "the next solar or lunar eclipse anywhere on Earth within a year, time of greatest eclipse"
}
},
"sun": {
"sunrise": {
"utc": "2026-08-10T04:36:07Z",
"local": "2026-08-10T06:36:07+02:00",
"timestamp": 1786336567,
"azimuth": 64.89
},
"solar_noon": {
"utc": "2026-08-10T11:55:58Z",
"local": "2026-08-10T13:55:58+02:00",
"timestamp": 1786362958,
"altitude": 56.61
},
"sunset": {
"utc": "2026-08-10T19:14:53Z",
"local": "2026-08-10T21:14:53+02:00",
"timestamp": 1786389293,
"azimuth": 294.82
},
"civil_dawn": {
"utc": "2026-08-10T04:00:18Z",
"local": "2026-08-10T06:00:18+02:00",
"timestamp": 1786334418
},
"civil_dusk": {
"utc": "2026-08-10T19:50:30Z",
"local": "2026-08-10T21:50:30+02:00",
"timestamp": 1786391430
},
"nautical_dawn": {
"utc": "2026-08-10T03:14:45Z",
"local": "2026-08-10T05:14:45+02:00",
"timestamp": 1786331685
},
"nautical_dusk": {
"utc": "2026-08-10T20:35:43Z",
"local": "2026-08-10T22:35:43+02:00",
"timestamp": 1786394143
},
"astronomical_dawn": {
"utc": "2026-08-10T02:20:53Z",
"local": "2026-08-10T04:20:53+02:00",
"timestamp": 1786328453
},
"astronomical_dusk": {
"utc": "2026-08-10T21:28:55Z",
"local": "2026-08-10T23:28:55+02:00",
"timestamp": 1786397335
},
"day_length_minutes": 878.8,
"golden_hour": [
{
"period": "morning",
"start": {
"utc": "2026-08-10T04:14:27Z",
"local": "2026-08-10T06:14:27+02:00",
"timestamp": 1786335267
},
"end": {
"utc": "2026-08-10T05:20:41Z",
"local": "2026-08-10T07:20:41+02:00",
"timestamp": 1786339241
}
},
{
"period": "evening",
"start": {
"utc": "2026-08-10T18:30:29Z",
"local": "2026-08-10T20:30:29+02:00",
"timestamp": 1786386629
},
"end": {
"utc": "2026-08-10T19:36:26Z",
"local": "2026-08-10T21:36:26+02:00",
"timestamp": 1786390586
}
}
],
"blue_hour": [
{
"period": "morning",
"start": {
"utc": "2026-08-10T04:00:18Z",
"local": "2026-08-10T06:00:18+02:00",
"timestamp": 1786334418
},
"end": {
"utc": "2026-08-10T04:14:27Z",
"local": "2026-08-10T06:14:27+02:00",
"timestamp": 1786335267
}
},
{
"period": "evening",
"start": {
"utc": "2026-08-10T19:36:26Z",
"local": "2026-08-10T21:36:26+02:00",
"timestamp": 1786390586
},
"end": {
"utc": "2026-08-10T19:50:30Z",
"local": "2026-08-10T21:50:30+02:00",
"timestamp": 1786391430
}
}
]
},
"moon": {
"name": "waning crescent",
"illuminated_fraction": 0.07581,
"age_days": 27.0114,
"waxing": false,
"distance_km": 363267.0,
"rise": {
"utc": "2026-08-10T01:02:42Z",
"local": "2026-08-10T03:02:42+02:00",
"timestamp": 1786323762,
"azimuth": 46.63
},
"transit": {
"utc": "2026-08-10T09:46:13Z",
"local": "2026-08-10T11:46:13+02:00",
"timestamp": 1786355173,
"altitude": 66.86
},
"set": {
"utc": "2026-08-10T18:15:21Z",
"local": "2026-08-10T20:15:21+02:00",
"timestamp": 1786385721,
"azimuth": 309.77
},
"state": "rises_and_sets",
"next_phase": {
"phase": "new_moon",
"utc": "2026-08-12T17:36:00Z",
"local": "2026-08-12T19:36:00+02:00",
"timestamp": 1786556160
}
},
"planets_tonight": [
{
"body": "saturn",
"from": {
"utc": "2026-08-10T22:16:01Z",
"local": "2026-08-11T00:16:01+02:00",
"timestamp": 1786400161
},
"to": {
"utc": "2026-08-11T04:01:52Z",
"local": "2026-08-11T06:01:52+02:00",
"timestamp": 1786420912
},
"best": {
"utc": "2026-08-11T03:30:00Z",
"local": "2026-08-11T05:30:00+02:00",
"timestamp": 1786419000,
"altitude": 44.51,
"azimuth": 180.11,
"magnitude": 0.58
},
"magnitude": 0.58
},
{
"body": "mars",
"from": {
"utc": "2026-08-11T01:42:16Z",
"local": "2026-08-11T03:42:16+02:00",
"timestamp": 1786412536
},
"to": {
"utc": "2026-08-11T04:01:52Z",
"local": "2026-08-11T06:01:52+02:00",
"timestamp": 1786420912
},
"best": {
"utc": "2026-08-11T04:00:00Z",
"local": "2026-08-11T06:00:00+02:00",
"timestamp": 1786420800,
"altitude": 31.96,
"azimuth": 89.71,
"magnitude": 1.29
},
"magnitude": 1.29
},
{
"body": "uranus",
"from": {
"utc": "2026-08-11T00:10:04Z",
"local": "2026-08-11T02:10:04+02:00",
"timestamp": 1786407004
},
"to": {
"utc": "2026-08-11T04:01:52Z",
"local": "2026-08-11T06:01:52+02:00",
"timestamp": 1786420912
},
"best": {
"utc": "2026-08-11T04:00:00Z",
"local": "2026-08-11T06:00:00+02:00",
"timestamp": 1786420800,
"altitude": 46.96,
"azimuth": 115.23,
"magnitude": 5.75
},
"magnitude": 5.75
}
],
"next_events": [
{
"type": "lunation",
"utc": "2026-08-12T17:37:00Z",
"local": "2026-08-12T19:37:00+02:00",
"timestamp": 1786556220,
"phase": "new_moon"
}
],
"next_eclipse": {
"kind": "solar",
"eclipse_type": "total",
"utc": "2026-08-12T17:46:00Z",
"local": "2026-08-12T19:46:00+02:00",
"timestamp": 1786556760,
"note": "greatest eclipse, global; whether and how it is seen from this place: astronomy/eclipse-local"
}
},
"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": "3e3b613747e151ba39228d7e71c806764db2c064a2294bed4c20c205a2583744",
"result_sha256": "9a5885bae51d624822ffd64c7d6d49a2d0132ae4d25074c20ef60f149c3a8e07",
"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 place, its time zone, the local date and the day's window in UTC. |
result.settings | object | The conventions of each block (they follow astronomy/rise-set, astronomy/moon and astronomy/visibility). |
result.sun | object | sunrise, solar_noon, sunset, civil/nautical/astronomical dawn and dusk, day_length_minutes, golden_hour and blue_hour [{period, start, end}]. |
result.moon | object | name, illuminated_fraction, age_days, waxing, distance_km, rise, transit, set, state and next_phase {phase, utc, local, timestamp} (null at the very end of the range). |
result.planets_tonight | array | The planets observable that night, brightest first: [{body, from, to, best: {utc, local, timestamp, altitude, azimuth, magnitude}, magnitude}]. |
result.next_events | array | Lunations ({phase}) and planetary stations ({body, turns}) of the next 7 days, each with utc, local and timestamp. |
result.next_eclipse | object | null | The next solar or lunar eclipse anywhere on Earth within a year: {kind, eclipse_type, utc, local, timestamp, note}, or null. |
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.