Moonphase API Documentation

Moon Phase Data

GET /api/v1/{date}

Returns comprehensive moon phase data for a specific date.

Parameters

Name	Type	Description
date	path (optional)	Date in YYYY-MM-DD format. Defaults to today.

date path (optional)

Date in YYYY-MM-DD format. Defaults to today.

Example Response

{
  "date": "2026-04-01",
  "phase": {
    "name": "Full Moon",
    "age": 14.77,
    "illumination": 100,
    "daysSinceFull": 0,
    "daysUntilFull": 30
  },
  "discPosition": 0.5,
  "synodicPeriod": 29.53059,
  "nearestFullMoon": "2026-04-01",
  "upcomingFullMoons": ["2026-05-01", "2026-05-31", ...]
}

Today Full Moon

GET /api/v1/range

Get moon phase data for a range of dates (max 366 days).

Query Parameters

Name	Type	Description
from	string	Start date (YYYY-MM-DD)
to	string	End date (YYYY-MM-DD)

from string

Start date (YYYY-MM-DD)

to string

End date (YYYY-MM-DD)

Example Response

{
  "from": "2026-04-01",
  "to": "2026-04-07",
  "count": 7,
  "data": [
    { "date": "2026-04-01", "phase": { "name": "Full Moon", "age": 14.77, "illumination": 100 } },
    { "date": "2026-04-02", "phase": { "name": "Waning Gibbous", "age": 15.77, "illumination": 98 } },
    ...
  ]
}

Try it

Phase Calendar

GET /api/v1/phases

Get all major phases (New Moon, First Quarter, Full Moon, Third Quarter) for a year.

Query Parameters

Name	Type	Description
year	number (optional)	Year (1900-2100). Defaults to current year.

year number (optional)

Year (1900-2100). Defaults to current year.

Example Response

{
  "year": 2026,
  "count": 49,
  "phases": [
    { "date": "2026-01-03", "phase": "Full Moon" },
    { "date": "2026-01-10", "phase": "Third Quarter" },
    { "date": "2026-01-18", "phase": "New Moon" },
    ...
  ]
}

2026 Phases

GET /api/v1/full-moons

Get all full moon dates for a year.

Query Parameters

Name	Type	Description
year	number (optional)	Year (1900-2100). Defaults to current year.

year number (optional)

Year (1900-2100). Defaults to current year.

2026 Full Moons

GET /api/v1/new-moons

Get all new moon dates for a year.

Query Parameters

Name	Type	Description
year	number (optional)	Year (1900-2100). Defaults to current year.

year number (optional)

Year (1900-2100). Defaults to current year.

2026 New Moons

Quick Lookups

GET /api/v1/next-full-moon

Get the next full moon date from today.

Example Response

{ "date": "2026-05-01", "daysUntil": 25 }

Try it

GET /api/v1/next-new-moon

Get the next new moon date from today.

Example Response

{ "date": "2026-04-17", "daysUntil": 11 }

Try it

GET /api/v1/{date}/watch-setting

Get watch setting instructions (clicks past full moon).

Example Response

{
  "date": "2026-04-06",
  "clicksPastFullMoon": 5,
  "instruction": "Set watch to 5 clicks past full moon",
  "phaseName": "Waning Gibbous"
}

Today Full Moon

Images

GET /api/v1/{date}/image.png

Returns a transparent PNG image of the moonphase disc.

Parameters

Name	Type	Description
date	path (optional)	Date in YYYY-MM-DD format. Defaults to today.
size	query (optional)	Width in pixels. Default: 300, Max: 1000

date path (optional)

Date in YYYY-MM-DD format. Defaults to today.

size query (optional)

Width in pixels. Default: 300, Max: 1000

Today PNG Full Moon PNG

GET /api/v1/{date}/image.svg

Returns an SVG image of the moonphase disc. Infinitely scalable, smaller file size.

Parameters

Name	Type	Description
date	path (optional)	Date in YYYY-MM-DD format. Defaults to today.

date path (optional)

Date in YYYY-MM-DD format. Defaults to today.

Today SVG Full Moon SVG

SVG vs PNG

SVG images are vector-based, so they scale perfectly to any size without losing quality. They're also typically smaller in file size. Use SVG when possible.

Notes

Timezone Handling

The API returns data for calendar dates. When calling without a date parameter, the server's local date is used. For your local "today", pass your date explicitly.

Accuracy

Moon phase calculations are accurate to within a few hours. The synodic period used is 29.53059 days.

Transparent Images

PNG images have transparent backgrounds, showing only the visible portion of the moon disc. Perfect for overlaying on any background.