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

ParameterTypeRequiredDefaultDescription
datestringyesThe local calendar day at the place, YYYY-MM-DD (1800-01-02..2199-12-30).
latitudenumberyesDecimal degrees, north positive.
longitudenumberyesDecimal degrees, east positive.
elevation_mnumber0Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled).
timezonestringIANA 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

FieldTypeDescription
result.subjectobjectThe place, its time zone, the local date and the day's window in UTC.
result.settingsobjectThe conventions of each block (they follow astronomy/rise-set, astronomy/moon and astronomy/visibility).
result.sunobjectsunrise, solar_noon, sunset, civil/nautical/astronomical dawn and dusk, day_length_minutes, golden_hour and blue_hour [{period, start, end}].
result.moonobjectname, 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_tonightarrayThe planets observable that night, brightest first: [{body, from, to, best: {utc, local, timestamp, altitude, azimuth, magnitude}, magnitude}].
result.next_eventsarrayLunations ({phase}) and planetary stations ({body, turns}) of the next 7 days, each with utc, local and timestamp.
result.next_eclipseobject | nullThe next solar or lunar eclipse anywhere on Earth within a year: {kind, eclipse_type, utc, local, timestamp, note}, or null.
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.