lunar

Get lunar phase

Returns lunar phase information for a specific datetime.

Performance: <10ms (trigonometric calculation via SuperNOVAS / Calceph)

Phase Names:

  • New Moon
  • Waxing Crescent
  • First Quarter
  • Waxing Gibbous
  • Full Moon
  • Waning Gibbous
  • Last Quarter
  • Waning Crescent

Data Returned:

  • Phase name and illumination percentage (0-100%)
  • Sun-Moon elongation angle (0-360°)
  • Waxing/waning classification
  • Moon age in days (~0-29.53 day cycle)
  • Moon distance from Earth (km)
  • Moon angular diameter (degrees)

Use Cases:

  • Daily lunar calendars
  • Gardening by Moon phase (Full Moon planting, etc.)
  • Manifestation/ritual timing (New Moon intentions, Full Moon releases)
  • General lunar awareness apps
  • Fishing/hunting activity timing

Example:

GET /ephemeris/moon/phase?datetime=2025-12-11T12:00:00Z
get/ephemeris/moon/phase

Request

  • Base URL: https://api.openephemeris.com
  • URL: https://api.openephemeris.com/ephemeris/moon/phase
  • Auth: one of:
    • HTTP bearer
    • API key in header X-OpenEphemeris-API-Key
    • API key in header X-API-Key
    • API key in header X-Service-Key

Query parameters

datetimestring required

ISO-8601 datetime, e.g. '2025-12-11T12:00:00Z'. A clock time must carry its own zone ('Z' or ±HH:MM); a zone-less clock time is rejected with 400 ambiguous_datetime. A date-only value resolves to 12:00 UTC.

formatstring

Response format: json | llm.

Headers

authorizationstring nullable
X-API-Keystring nullable
X-OpenEphemeris-API-Keystring nullable
apikeystring nullable

Response

Successful Response

days_to_fullnumber

Days until next Full Moon

days_to_newnumber

Days until next New Moon

illuminationnumber required

Moon illumination percentage (0-100)

metadataobject required

Calculation metadata

moon_degreenumber

The Moon's degree within its sign (0-30).

moon_longitudenumber

The Moon's ecliptic longitude in degrees (0-360).

moon_signstring

Zodiac sign the Moon occupies at this instant (e.g. 'Capricorn'). Also present in metadata.moon_sign for backwards compatibility.

phase_anglenumber required

Sun-Moon angle in degrees (0-360)

phase_namestring required

Phase name (New Moon, Waxing Crescent, First Quarter, Waxing Gibbous, Full Moon, Waning Gibbous, Last Quarter, Waning Crescent)

successboolean

Calculation success status

waxingboolean required

True if Moon is waxing

Example response

{
  "days_to_full": 2.5,
  "days_to_new": 12.3,
  "illumination": 78.5,
  "metadata": {
    "calculation_time_ms": 5.2
  },
  "moon_degree": 14.2,
  "moon_longitude": 284.2,
  "moon_sign": "Capricorn",
  "phase_angle": 125.3,
  "phase_name": "Waxing Gibbous",
  "success": true,
  "waxing": true
}

Changes

No recorded changes to this operation across all 1 revision of this API.