Docs › Moon phase, illumination, distance and next phases

Moon phase, illumination, distance and next phases

The Moon at a moment: phase name and angle, illuminated fraction, age, lunation number, distance and apparent size, the next new, first quarter, full and last quarter Moons, and the next perigee and apogee.

POST https://astro-agent.dev/v1/astronomy/moon · $0.01 per call · MCP tool moon_details · Try it in the playground

For calendar, weather, photography and tide apps: phase (8 names), phase angle, illuminated fraction, waxing or waning, age in days since the new Moon, Brown lunation number, centre-to-centre distance in km and Earth radii, angular diameter, ecliptic position, the previous new Moon, the next four principal phases and the next perigee and apogee with their distances, to the second. With latitude/longitude: the Moon's altitude and azimuth there and that local day's moonrise, transit and moonset. Perigee and apogee match NASA/JPL Horizons to the minute.

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
datetimestringThe moment: UTC, an explicit offset, or local civil time at the place given by latitude/longitude. Default: now (UTC, to the minute).
latitudenumberOptional: add the Moon's altitude and azimuth from this place and that local day's moonrise, transit and moonset.
longitudenumberOptional, with latitude.
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/moon \
  -H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datetime": "2026-01-03T12:00:00Z", "latitude": 48.8566, "longitude": 2.3522}'

Python

import os
import requests

body = {'datetime': '2026-01-03T12:00:00Z', 'latitude': 48.8566, 'longitude': 2.3522}
r = requests.post("https://astro-agent.dev/v1/astronomy/moon", 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()

p = data["result"]["phase"]
print(p["name"], f'{p["illuminated_fraction"]:.0%} lit, {p["age_days"]:.1f} days old')
print("Distance", data["result"]["distance"]["km"], "km")
for ph in data["result"]["next_phases"]:
    print(ph["phase"], ph["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 = {"datetime": "2026-01-03T12:00:00Z", "latitude": 48.8566, "longitude": 2.3522};
const res = await fetch("https://astro-agent.dev/v1/astronomy/moon", {
  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 p = data.result.phase;
console.log(p.name, Math.round(p.illuminated_fraction * 100) + "% lit,", p.age_days.toFixed(1), "days old");
console.log("Distance", data.result.distance.km, "km");
for (const ph of data.result.next_phases) console.log(ph.phase, ph.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:

c3974e1638d920379948c5e3f995bcf1558b5604e4966ba0dd64bb44589c9910

{
  "endpoint": "astronomy/moon",
  "result": {
    "subject": {
      "time": {
        "local_input": "2026-01-03T12:00:00Z",
        "time_basis": "civil",
        "timezone": null,
        "timezone_source": "offset_in_datetime",
        "utc_offset": "+00:00",
        "is_dst": null,
        "utc": "2026-01-03T12:00:00Z",
        "julian_day_ut": 2461044.000001,
        "julian_day_tt": 2461044.000801,
        "delta_t_seconds": 69.11,
        "time_known": true,
        "local_mean_time": "2026-01-03T12:09:24",
        "true_solar_time": "2026-01-03T12:04:55",
        "equation_of_time_minutes": -4.4903
      }
    },
    "settings": {
      "conventions": {
        "frame": "geocentric apparent positions (Earth's centre), true ecliptic and equinox of date",
        "phase_angle": "Moon's ecliptic longitude minus the Sun's, 0-360 (0 new, 90 first quarter, 180 full, 270 last quarter)",
        "illuminated_fraction": "from the Sun-Moon-Earth phase angle (Skyfield fraction_illuminated)",
        "age": "days since the previous new Moon",
        "lunation": "Brown lunation number (1 = the new Moon of 1923-01-17)",
        "distance": "Earth's centre to the Moon's centre, km; perigee/apogee = its minima/maxima, to the minute",
        "local": "with latitude/longitude: topocentric apparent altitude and azimuth (refraction applied), and that local day's moonrise, transit and moonset (astronomy/rise-set conventions)"
      }
    },
    "phase": {
      "name": "full moon",
      "phase_angle": 181.1265,
      "illuminated_fraction": 0.99855,
      "waxing": false,
      "age_days": 14.4282,
      "lunation": 1274
    },
    "distance": {
      "km": 362526.9,
      "earth_radii": 56.839,
      "angular_diameter_arcmin": 32.951
    },
    "position": {
      "ecliptic_longitude": 104.24223,
      "ecliptic_latitude": 4.2246
    },
    "previous_new_moon": {
      "utc": "2025-12-20T01:43:21Z",
      "timestamp": 1766195001
    },
    "next_phases": [
      {
        "phase": "last_quarter",
        "utc": "2026-01-10T15:48:24Z",
        "timestamp": 1768060104
      },
      {
        "phase": "new_moon",
        "utc": "2026-01-18T19:51:59Z",
        "timestamp": 1768765919
      },
      {
        "phase": "first_quarter",
        "utc": "2026-01-26T04:47:23Z",
        "timestamp": 1769402843
      }
    ],
    "next_perigee": {
      "utc": "2026-01-29T21:54:25Z",
      "timestamp": 1769723665,
      "distance_km": 365894.2
    },
    "next_apogee": {
      "utc": "2026-01-13T20:52:49Z",
      "timestamp": 1768337569,
      "distance_km": 405404.8
    },
    "local": {
      "location": {
        "latitude": 48.8566,
        "longitude": 2.3522,
        "elevation_m": 0.0
      },
      "timezone": "Europe/Paris",
      "timezone_source": "resolved_from_coordinates",
      "date": "2026-01-03",
      "window_utc": {
        "start": "2026-01-02T23:00:00Z",
        "end": "2026-01-03T23:00:00Z"
      },
      "altitude": -15.2352,
      "azimuth": 359.5519,
      "above_horizon": false,
      "rise": {
        "utc": "2026-01-03T15:54:19Z",
        "local": "2026-01-03T16:54:19+01:00",
        "timestamp": 1767455659,
        "azimuth": 47.61
      },
      "transit": {
        "utc": "2026-01-02T23:29:18Z",
        "local": "2026-01-03T00:29:18+01:00",
        "timestamp": 1767396558,
        "altitude": 68.62
      },
      "set": {
        "utc": "2026-01-03T08:15:08Z",
        "local": "2026-01-03T09:15:08+01:00",
        "timestamp": 1767428108,
        "azimuth": 313.78
      },
      "state": "rises_and_sets"
    }
  },
  "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": "69b8e65162f19afcb232b237ad6470752ad2a70a1c6c527df63a483a6512e236",
    "result_sha256": "c3974e1638d920379948c5e3f995bcf1558b5604e4966ba0dd64bb44589c9910",
    "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 resolved moment ('time': input, UTC, Julian days, Delta T).
result.settingsobjectEvery convention: frame, phase angle, illumination, age, lunation, distance.
result.phaseobjectname (new moon, waxing crescent... waning crescent), phase_angle (0-360), illuminated_fraction, waxing, age_days, lunation (Brown).
result.distanceobjectkm, earth_radii and angular_diameter_arcmin.
result.positionobjectGeocentric apparent ecliptic_longitude and ecliptic_latitude, degrees.
result.previous_new_moonobject | null{utc, timestamp} of the last new Moon (null within a month of 1800-01-01).
result.next_phasesarrayThe next new, first quarter, full and last quarter Moons in time order: [{phase, utc, timestamp}].
result.next_perigeeobject | null{utc, timestamp, distance_km} of the next closest approach (null when it falls after 2199-12-30).
result.next_apogeeobject | null{utc, timestamp, distance_km} of the next farthest point (null when it falls after 2199-12-30).
result.localobjectWith latitude/longitude only: location, time zone, altitude, azimuth, above_horizon and that local day's rise, transit, set and state.
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).

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/moon?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.