---
title: "Calculate lunar phase for datetime"
method: POST
path: "/ephemeris/lunar-phase"
tags: ["ephemeris"]
---

# Calculate lunar phase for datetime

`POST /ephemeris/lunar-phase`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/ephemeris/lunar-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`

Calculate the current lunar phase based on Sun-Moon elongation. Returns phase name/angle, illumination percentage, and lunation metadata (New Moon/Full Moon dates, day of lunation, void-of-course status). 🤖 AI-optimized output available — add `format=llm` to reduce payload ~50%.

## Query parameters

- `output_mode` string, nullable
- `format` string

## Headers

- `authorization` string, nullable
- `X-API-Key` string, nullable
- `X-OpenEphemeris-API-Key` string, nullable
- `apikey` string, nullable

## Request body

- LunarPhaseCalculationRequest: Request for calculating lunar phase data.
  - `date_time` DateTimeInput, required: Date/time input in ISO-8601, component, or Julian day form. A value that states a clock time must also state its zone, either as a suffix on the string or via the `timezone` field below.
    - `components` object: Date/time components (year, month, day, and optionally hour, minute, second). If hour/minute are present, pass `timezone` alongside them; without it the request is rejected with 400 ambiguous_datetime. Omit the clock entirely and the date resolves to 12:00 UTC.
    - `iso` string: ISO-8601 datetime (supported range 1550–2650 CE, JPL DE440). If it states a clock time it must carry its zone: either a 'Z'/±HH:MM suffix on the string ("1987-07-15T09:01:00-05:00"), or a `timezone` passed alongside it. A zone-less clock time is rejected with 400 ambiguous_datetime — it is not read as UTC. A date-only value ("1987-07-15") has no clock to be ambiguous about and resolves to 12:00 UTC.
    - `julian_day` number, double: Julian Day Number (always UTC-based, so it needs no zone)
    - `timezone` TimezoneInput: Timezone input using IANA names or UTC offsets.
      - `fold_preference` 'earlier' | 'later': Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user.
      - `iana_name` string: IANA timezone name
      - `time_standard` 'auto' | 'standard' | 'daylight': How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used.
      - `utc_offset` number: UTC offset in hours

## Response `200`

Successful Response

- LunarPhaseCalculationResponse: Response from lunar phase calculation endpoint.
  - `metadata` object, required: Calculation metadata and settings
  - `phase` LunarPhaseData, required: Lunar phase information at a specific moment.
    - `age_days` number, required: Age of Moon in days since last New Moon
    - `angular_diameter` number, required: Angular diameter of Moon in degrees
    - `distance_km` number, required: Earth-Moon distance in kilometers
    - `elongation` number, required: Sun-Moon elongation in degrees (0-180)
    - `illumination` number, required: Percentage of lunar disk illuminated (0-100)
    - `name` string, required: Phase name (New Moon, Waxing Crescent, First Quarter, etc.)
    - `phase_angle` number, required: Phase angle in degrees (0-360)
  - `success` boolean: Calculation success status

## Other responses

- `400`: Bad Request
- `422`: Unprocessable Entity - Invalid input format
- `500`: Internal Server Error

---

[API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)