# Moon Phase Calculator

> Estimates the Moon's phase name, illuminated fraction and age (days since new moon) for a calendar date from the mean synodic month of 29.530588853 days counted from the new moon of 2000-01-06 18:14 UTC, plus the dates of the next new and full moons.

- Calculator id: `moon-phase` · Category: Time & Geography (`time`) · Tool name: `calculate_moon_phase`
- Canonical page: https://tttkmbb.com/time/moon-phase · This document: https://tttkmbb.com/time/moon-phase.md · JSON definition: https://tttkmbb.com/time/moon-phase.json

## Purpose

Estimates the Moon's phase name, illuminated fraction and age (days since new moon) for a calendar date from the mean synodic month of 29.530588853 days counted from the new moon of 2000-01-06 18:14 UTC, plus the dates of the next new and full moons.

**Use when:** You need the approximate lunar phase for a date, e.g. for night photography, fishing or tide context, gardening calendars or historical dates.

**Do not use when:** You need phase times to the hour, eclipse predictions or moonrise/moonset (use an ephemeris such as USNO or JPL Horizons); for daylight times use sunrise-sunset.

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `date` | date |  | optional, default "today" | Calendar date (YYYY-MM-DD); the phase is evaluated at 12:00 UTC of that day. Defaults to the current UTC date. |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `phase_name` | string |  | One of the eight phases: New Moon, Waxing Crescent, First Quarter, Waxing Gibbous, Full Moon, Waning Gibbous, Last Quarter, Waning Crescent. |
| `illumination_percent` | number | % | Fraction of the disc that is lit, from the phase angle: (1 − cos(2π · fraction)) / 2. |
| `age_days` | number | days | Days since the last (mean) new moon at 12:00 UTC on the date. |
| `phase_fraction` | number |  | Position in the lunation from 0 (new) through 0.5 (full) to 1 (next new). |
| `is_waxing` | boolean |  | true while illumination increases (new to full). |
| `next_new_moon_date` | date |  | Date (UTC) of the next mean new moon, ±1 day. |
| `next_full_moon_date` | date |  | Date (UTC) of the next mean full moon, ±1 day. |
| `days_until_next_full_moon` | number | days | From 12:00 UTC on the date to the next mean full moon. |

## Formula

`age = (JD(date 12:00 UTC) − 2451550.2597) mod 29.530588853; fraction = age / 29.530588853; illumination = (1 − cos(2π · fraction)) / 2; phase index = floor(((fraction + 1/16) mod 1) × 8)`

Uses the mean lunation only; the true phase can lead or lag the mean by up to about 14 hours because of the Moon's elliptical orbit, so phase names and dates are accurate to about ±1 day and illumination to roughly ±10 percentage points near the quarters. Each named phase spans one eighth of the cycle (±1/16 around the exact event).

## Data Sources

- USNO Astronomical Applications – Phases of the Moon — https://aa.usno.navy.mil/data/MoonPhases (government, retrieved 2026-09-24)
- Lunar phase (Wikipedia) — https://en.wikipedia.org/wiki/Lunar_phase (reference, retrieved 2026-09-24)
- Lunar month – synodic month 29.530588 days (Wikipedia) — https://en.wikipedia.org/wiki/Lunar_month (reference, retrieved 2026-09-24)

Data freshness: `daily` (max_age_seconds 86400). Depends on the current date unless the date is supplied.

## API

- `GET https://tttkmbb.com/api/v1/calculate/moon-phase?`
- `POST https://tttkmbb.com/api/v1/calculate/moon-phase` with JSON body `{"inputs": {…}}`
- Response: unified envelope (`success`, `request`, `result.values`, `result.units`, `sources`, `freshness`, `timestamp`, `next_actions`, `links`); see https://tttkmbb.com/docs/response-format.md
- Schema: https://tttkmbb.com/api/v1/calculators/moon-phase · OpenAPI operationId `calculate_moon_phase` in https://tttkmbb.com/openapi.json
- Authentication: none. Rate limit: fair use, see https://tttkmbb.com/docs/rate-limits.md.

## MCP

- Server: `https://tttkmbb.com/mcp` (Streamable HTTP, JSON-RPC 2.0, no auth)
- Tool:  `run_calculator` with `{"calculator_id": "moon-phase", "inputs": {…}}`

## Example

- 2026-08-12 (new moon and total solar eclipse): inputs `{"date":"2026-08-12"}` → `{"phase_name":"New Moon","is_waxing":false,"next_full_moon_date":"2026-08-28"}`
- 2026-03-03 (full moon and total lunar eclipse): inputs `{"date":"2026-03-03"}` → `{"phase_name":"Full Moon","illumination_percent":99.8,"age_days":14.36,"is_waxing":true}`

```
GET https://tttkmbb.com/api/v1/calculate/moon-phase?date=2026-08-12
```

## Limitations

You need phase times to the hour, eclipse predictions or moonrise/moonset (use an ephemeris such as USNO or JPL Horizons); for daylight times use sunrise-sunset. Uses the mean lunation only; the true phase can lead or lag the mean by up to about 14 hours because of the Moon's elliptical orbit, so phase names and dates are accurate to about ±1 day and illumination to roughly ±10 percentage points near the quarters. Each named phase spans one eighth of the cycle (±1/16 around the exact event). All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**How accurate is the phase?**

Within about one day: the mean synodic month ignores the orbital perturbations that shift real new and full moons by up to ±14 hours. USNO's Phases of the Moon table gives exact times.

**Is the illumination the same everywhere on Earth?**

Yes; the illuminated fraction depends only on the Sun–Earth–Moon geometry. Only the orientation of the lit side differs between hemispheres (the waxing side appears on the right in the north and on the left in the south).

## Related

- [Sunrise and Sunset Calculator](https://tttkmbb.com/time/sunrise-sunset.md) — Sunrise and sunset for the same date and place.
- [Julian Date Calculator](https://tttkmbb.com/time/julian-date.md) — Julian Date used to count lunations.
- [Days Until Calculator](https://tttkmbb.com/everyday/days-until.md) — Countdown to the next full moon date.