Moon Phase Calendar Data

What is the Moon Phase Calendar endpoint?

You need a complete lunar calendar for a given month and location. The Moon Phase Calendar endpoint takes a month, year, and place, and returns two arrays: a day-by-day phase breakdown for every date in the month (with illumination percent and moon age), and a list of exact timestamps when the Moon transitions from one major phase to the next.

This endpoint is part of the Natal Chart API.

Why does this endpoint exist?

You are building a lunar calendar UI, planner widget, or astrology dashboard that needs daily Moon data across a whole month. Computing each day's phase, illumination percent, and Moon age yourself means iterating ephemeris queries day by day. Computing the exact timestamp when the Moon hits a major phase boundary takes interpolation. This endpoint runs both at once and returns a single structured response.

What inputs does it need?

You pass the month, year, and location coordinates rather than full birth data. Authentication uses a Bearer token in the Authorization header. The endpoint scopes to the timezone offset you supply, so all returned timestamps are in local time.

What does the response data look like?

You get a data object with two arrays. The month_phases array carries one entry per calendar day with the day's phase, illumination percent, moon age, and Sun-Moon angular distance. The phases_change_list array lists exact timestamps for each major phase transition during the month.

What does a real response look like?

Below is a slice of the response for May 2023, New Delhi (IST). The full response includes 31 daily entries and 9 phase transitions; this slice shows the Full Moon transition on May 5 alongside the surrounding daily entries.

{
  "success": 1,
  "data": {
    "month_phases": [
      { "date": "2023-05-04", "phase_no": 4, "phase_name": "Waxing Gibbous Moon", "phase_degree": 156.0822, "moon_age": 14, "illumination": 99.34 },
      { "date": "2023-05-05", "phase_no": 5, "phase_name": "Full Moon", "phase_degree": 168.1312, "moon_age": 15, "illumination": 100 },
      { "date": "2023-05-06", "phase_no": 6, "phase_name": "Waning Gibbous Moon", "phase_degree": 180.4856, "moon_age": 16, "illumination": 98.28 }
    ],
    "phases_change_list": [
      { "datetime": "2023-05-05 23:05:00", "phase_no": 5, "phase_name": "Full Moon", "phase_degree": 180 },
      { "datetime": "2023-05-12 19:59:00", "phase_no": 7, "phase_name": "Last Quarter Moon", "phase_degree": 270 },
      { "datetime": "2023-05-19 21:24:00", "phase_no": 1, "phase_name": "New Moon", "phase_degree": 0 }
    ]
  }
}

What can you build with this endpoint?

You use the Moon Phase Calendar whenever your product needs a month-long lunar view. The two-array response covers both calendar-grid rendering (one cell per day) and event-based UI (highlighting phase transition moments).

1. Lunar calendar widget. Render a month grid with phase icons on each date, populated directly from month_phases.
2. Phase transition reminders. Use phases_change_list to schedule notifications or surface "Full Moon at 23:05 tonight" banners.
3. Astrology planners. Combine illumination percent and moon age fields with daily horoscope content for ritual or planning apps.
4. Lunar-cycle dashboards. Plot illumination percent over the month for a visual cycle graph next to the calendar grid.

How accurate is the calculation?

You are computing daily phase data and exact phase-transition timestamps. Both come from Swiss Ephemeris with NASA JPL ephemeris data underneath. The illumination values are computed from the same Sun-Moon angle that drives phase_degree, so the two stay consistent across the dataset.

The phases_change_list timestamps land on the exact moment the Sun-Moon angle hits a phase anchor (0°, 90°, 180°, 270° for major transitions). All datetimes return in the timezone you passed via tzone, so a user in IST sees IST times without client-side conversion.

How does this relate to the parent API?

You are building lunar features that span a full month rather than a single birth moment. This endpoint complements the Natal Chart API by providing time-series lunar data for a given month and location, rather than a single-point natal calculation.

The Moon Phases endpoint covers the lunar phase at a specific birth instant. This endpoint covers a whole month from any reference point. Use this one for calendar UI, planner apps, and lunar-cycle content. Use Moon Phases for natal-chart lunar interpretation tied to a birth date.

Summary

The Moon Phase Calendar endpoint returns a full month of daily lunar data plus exact phase-transition timestamps for any month and location. The month_phases array drives calendar grids; the phases_change_list powers transition notifications and event UI. It runs on Swiss Ephemeris with NASA JPL ephemeris data and respects the timezone you pass in. Use it for any lunar feature that spans more than a single moment.

For related calculations, see moon-phases-lunar-positions and eclipse-detection-in-natal-charts. To call this in production, integrate with the western-astrology-api.