Moon phases and event calendar

Beta physical phase geometry and primary Moon-phase events from the existing DE421 ephemeris.

POST /api/astro/moon-phases requires a server-side API key. All plans use one standard quota unit per admitted attempt, including invalid input, engine failure and timeout. Do not automatically retry.

Public endpoint: https://api.astroapi.io/api/astro/moon-phases. Send Authorization: Bearer YOUR_API_KEY and Content-Type: application/json; load the real key from your server environment.

Choose one explicit mode

  • instant: provide at. Returns a display phase sector, Moon-minus-Sun ecliptic longitude, waxing/waning longitude cycle and separately computed illuminated fraction.
  • calendar: provide start and end. Returns new Moon, first quarter, full Moon and last quarter events.

Each civil input contains date, time and optional IANA timezone (default UTC). display_timezone changes output labels only and also defaults to UTC. No coordinates, zodiac, ayanamsa, chart, URL or custom ephemeris is accepted.

Calendar and timezone boundaries

Civil dates are 1900-01-01 through 2050-12-31. UTC conversion must also stay within supported coverage. Ambiguous or nonexistent local times return 400; provide the known UTC instant instead. The interval must be positive and at most 366 elapsed UTC days.

Membership uses reported event timestamps: start inclusive, end exclusive. Events round to the nearest second and are ordered without duplicates; an interval can validly contain no events. At most 52 events are returned. An event in an unsupported leap second fails explicitly.

What the values mean

Optional calendar download: add include_ical: true in calendar mode to receive result.ical. Save this decoded string unchanged as a UTF-8 .ics file; do not save the surrounding JSON or replace its CRLF line endings. An empty event window returns ical: null, so create no file. Omitted or false leaves the existing response unchanged. This option is invalid in instant mode.

The export contains UTC point events with fixed English labels, transparent availability and stable IDs for the same model, phase and reported second. Calendar applications choose their own display timezone and import behavior; display_timezone does not move events. The export timestamp records file assembly, so it can change between requests. Files contain at most 52 events and 32 KiB. No subscription feed, alarm, invitation or customer webhook is created. Calendar-provider import acceptance has not yet been performed.

The eight phase_sector names are nearest-45-degree display bins. A “new_moon” sector does not mean the instant is the exact new Moon. Primary calendar events are crossings of 0°, 90°, 180° and 270° in Moon-minus-Sun ecliptic longitude.

illuminated_fraction is a number from 0 to 1 from spherical Sun–Moon–observer geometry. It is not measured brightness and excludes eclipse shadows, terrain, atmosphere and crescent visibility. The longitude cycle is not the derivative of illuminated area. No regional festival, muhurta or astrological interpretation is supplied.

Precision is not an accuracy guarantee

The search converges to 0.001 seconds and reports calendar timestamps to one second. Those are numerical/output settings, not a promise of millisecond astronomical accuracy. All 50 USNO 2026 reference events compare within 60 seconds; selected independent historical TT references provide additional checks. Broad-epoch specialist acceptance remains open.

UTC uses Skyfield’s bundled time-scale data. Future UTC assumes the known leap-second schedule, so future civil event times can change after a reviewed time-data update. UT1, TT and UTC are different time scales; compare reference tables in the same scale.

Responses and errors

Responses contain type: "moon_phases", status: "beta", the selected mode, result and explicit metadata. Result fields differ by mode. Calendar results include events, interval boundaries, model and numerical limits.

Malformed inputs return 400. Authentication, quota and concurrency errors retain the standard API behavior. Upstream failure or timeout returns 502/504; internal calculation details are not exposed.

See the complete OpenAPI contract, Postman collection and API overview.

Instant request

{
  "mode": "instant",
  "at": {"date": "2026-01-18", "time": "19:52", "timezone": "UTC"},
  "display_timezone": "America/New_York"
}

Calendar request

{
  "mode": "calendar",
  "start": {"date": "2026-01-01", "time": "00:00", "timezone": "UTC"},
  "end": {"date": "2026-02-01", "time": "00:00", "timezone": "UTC"},
  "include_ical": true
}

Node.js 22+ — server only

import { AstroAPI } from "@astroapi/node";
const api = new AstroAPI(); // Reads ASTROAPI_KEY.
const phase = await api.moonPhases({
  mode: "instant",
  at: { date: "2026-01-18", time: "19:52", timezone: "UTC" }
});
console.log(phase.result.phase_sector);

Python — server only

from astroapi_client import AstroAPIClient
api = AstroAPIClient()  # Reads ASTROAPI_KEY.
result = api.moon_phases({
    "mode": "calendar",
    "start": {"date": "2026-01-01", "time": "00:00"},
    "end": {"date": "2026-02-01", "time": "00:00"},
    "include_ical": True
})
print(len(result["result"]["events"]))

Read the downloadable value with result["result"]["ical"] in Python or result.result.ical in Node.js after a calendar request with the option enabled. If serving the decoded file from your own backend, use Content-Type: text/calendar; charset=utf-8 and a fixed safe attachment filename. AstroAPI itself still returns JSON.

SDK source packages require local installation from the repository; registry publication is separate. Each example makes one billable call. Keep credentials out of browser bundles and shared collections.