Moon Phase Endpoint #

POST /api/v5/moon-phase #

View Complete Example

This endpoint returns detailed moon phase information for a specific date/time and geographic location. It computes lunar illumination, phase timing, upcoming major phases, eclipse predictions, and solar data (sunrise/sunset, sun position).

Unlike other endpoints, this uses a simplified flat request model — no subject wrapper, no name, city, or nation fields. Only date/time and geographic coordinates are required.

Important: This endpoint uses strict validation. Unknown/extra fields (e.g., name, city, nation) in the request body will be rejected with a 422 error.

Use Cases #

• Displaying current moon phase in an app.
• Tracking lunar cycles for gardening, fishing, or wellness apps.
• Showing upcoming full/new moon dates.
• Eclipse prediction features.
• Sunrise/sunset calculators.

Request Body #

The request body contains date/time and location fields directly (no subject wrapper).

• year (integer, required): Year of the event (1-3000).
• month (integer, required): Month (1-12).
• day (integer, required): Day (1-31).
• hour (integer, required): Hour (0-23).
• minute (integer, required): Minute (0-59).
• second (integer, optional): Seconds (0-59, default: 0).
• latitude (float, required): Latitude (-90 to 90).
• longitude (float, required): Longitude (-180 to 180).
• timezone (string, required): IANA timezone identifier (e.g., "Europe/London", "America/New_York").
• using_default_location (boolean, optional): Metadata flag indicating default location (default: false).
• location_precision (integer, optional): Number of decimal places used to round latitude and longitude in the response (0-10, default: 0). This is display rounding only — calculations always use the full-precision input coordinates.

Complete Request Example #

{
    "year": 1993,
    "month": 10,
    "day": 10,
    "hour": 12,
    "minute": 12,
    "second": 0,
    "latitude": 51.5074,
    "longitude": -0.1276,
    "timezone": "Europe/London",
    "using_default_location": false,
    "location_precision": 4
}

Minimal Request Example #

{
    "year": 1993,
    "month": 10,
    "day": 10,
    "hour": 12,
    "minute": 12,
    "latitude": 51.5074,
    "longitude": -0.1276,
    "timezone": "Europe/London"
}

Response Body #

The response contains status and a moon_phase_overview object with the following sections:

Top-Level Fields #

Moon Section (moon_phase_overview.moon) #

Eclipse Section #

Detailed Moon Data (moon.detailed) #

Sun Section (moon_phase_overview.sun) #

Note on naming: sunrise and sunset are Unix timestamps (integers). sunrise_timestamp and sunset_timestamp are human-readable local time strings — the _timestamp suffix refers to the formatted representation, not a Unix timestamp.

Location Section (moon_phase_overview.location) #

Error Responses #

This endpoint returns 422 Unprocessable Entity in the following cases:

• Missing required fields: Any of year, month, day, hour, minute, latitude, longitude, or timezone is omitted.
• Invalid timezone: The timezone value is not a valid IANA timezone identifier (e.g., "Foo/Bar").
• Out-of-range values: Coordinates outside valid ranges (latitude: -90 to 90, longitude: -180 to 180), or time fields outside their ranges.
• Extra/unknown fields: Any field not listed above (e.g., name, city, nation, subject) is sent. This endpoint uses strict validation and rejects unknown fields.