MOONPHASE Function
The MOONPHASE function returns a fractional numeric value representing the Moon's phase on a specified date. The value identifies its position within the lunar cycle, also called the lunation cycle, and distinguishes a waxing Moon from a waning Moon.
Format:
- MOONPHASE(Date)
where Date is a date, optionally including a time. Depending on where the formula is used, this can be:
- in a report — a column containing a date, such as D;
- in a calculated task field — a date field variable, such as {{Task.Creation date}};
- a date string, such as "09-11-2026 07:02" in DD-MM-YYYY HH:mm format.
The input is interpreted in the user's time zone, including the daylight saving time rules applicable on that date. If no time is specified, midnight — 00:00 — is used.
Return value
The function returns a number greater than −4 and less than or equal to 4. The main reference points are:
| Value | Lunar phase |
|---|---|
| 0 | New Moon |
| 1 | Crescent Moon — waxing crescent |
| 2 | First Quarter |
| 3 | Gibbous Moon — waxing gibbous |
| 4 | Full Moon |
| −3 | Disseminating Moon — waning gibbous |
| −2 | Last Quarter — also called Third Quarter |
| −1 | Balsamic Moon — waning crescent |
Between these reference points, the function returns fractional values. For example, 1.5 represents a position between the Crescent Moon and First Quarter reference points.
To identify the Moon's state:
- 0 — the moment of the New Moon;
- greater than 0 and less than 4 — a waxing Moon;
- 4 — the moment of the Full Moon;
- less than 0 — a waning Moon.
The sign changes at the Full Moon. Immediately before it, the value approaches 4. At the Full Moon, it equals 4. Immediately afterward, it changes to a value close to −4, then increases toward 0 as the next New Moon approaches.
The numeric encoding is a Planfix convention. The returned value represents a position within the lunar cycle, rather than the percentage of the Moon's illuminated surface.
Astrological terminology
The phase names follow the eight-phase lunation cycle used in Western astrology, including the Disseminating and Balsamic phases.
For background on these terms, see CHANI's guide to the eight lunar phases.
Calculation accuracy
For dates from 2000 through 2050 inclusive, the calculation uses tabulated times of New Moons, First Quarters, Full Moons, and Last Quarters from NASA:
The tabulated times are rounded to the nearest minute.
Values between consecutive primary phases are calculated using linear interpolation. Intermediate values are therefore approximate. The reference values 1, 3, −3, and −1 occur halfway in time between the corresponding primary phases.
For dates before 2000 or after 2050, the function uses an approximate calculation based on the average length of a synodic month.
If a date string cannot be recognized, the function returns 0.
Examples
In a report
Return the lunar phase for the date in column D:
MOONPHASE(D)
Here, D is a report column containing a date. Replace D with your own column identifier.
In a calculated task field
Return the lunar phase at the time the task was created:
MOONPHASE({{Task.Creation date}})
Return the same value rounded to two decimal places:
ROUND(MOONPHASE({{Task.Creation date}}); 2)
You can replace the creation date with any task date field variable. Insert the variable using the variable selector in the calculated field settings.
When checking for a New Moon, Full Moon, or waxing/waning state, use the value before rounding. Rounding can turn a value close to 0 or 4 into the corresponding whole number.
Using a date string
MOONPHASE("09-11-2026 07:02")
The date is November 9, 2026. If the user's time zone is UTC, the result is 0 — a New Moon. In another time zone, the same string represents a different instant, so the result will differ.