WESTERN ASTROLOGY · JSON REST API

Moon Phases API

Build a lunar calendar from solved Sun–Moon elongation events. This endpoint needs a date window, not a personal birth chart, and returns the four principal phases as UTC instants.

AvailablePOST /v1/astrology/moon-phases

50,000 credits per monthly allowance · no trial · no automatic overage charges. Plan details ↗

BUILD AROUND THE DATA

What this API provides.

Get exact new moon, first quarter, full moon and last quarter times from JPL-based apparent ecliptic elongation. View a real lunar-event sample.

01

New moon, first quarter, full moon and last quarter

02

Roots at 0°, 90°, 180° and 270° elongation

03

1–365-day UTC date windows

04

JPL DE440s calculation profile and solver metadata

Send

  • start_date in Gregorian YYYY-MM-DD form
  • days from 1 to 365
  • Optional locale for phase descriptions; no birth location is required

Receive

  • events with phase, target elongation and exact UTC timestamp
  • Declared start-inclusive, end-exclusive range
  • Calculation profile, tolerances and localized phase text
COMPUTED EVENT PREVIEW

A time, not a daily guess.

The first 1 events from the real result. Download the complete response for all events, methods and residuals.

  1. first quarterElongation 90°
INSPECT BEFORE SUBSCRIBING

Real input. Real output.

Precomputed by the actual calculation engine and response formatter, using synthetic example data. No purchased access or paid provider call was needed.

Request JSON POST /v1/astrology/moon-phases
{
  "locale": "en",
  "start_date": "2026-11-17",
  "days": 7
}
Response JSON · selected fields
{
  "request_id": "57f1f0affcba524ca8aa3cb0056a90a7",
  "api_version": "v1",
  "locale": "en",
  "data": {
    "window": {
      "start_at": "2026-11-17T00:00:00Z",
      "end_at_exclusive": "2026-11-24T00:00:00Z",
      "days": 7
    },
    "events": [
      {
        "at": "2026-11-17T11:47:49.647Z",
        "phase": "first_quarter",
        "elongation_deg": 90.00000013,
        "target_elongation_deg": 90
      }
    ],
    "method": {
      "type": "apparent_geocentric_ecliptic_elongation",
      "solver": "bracketed_bisection",
      "search_scale": "TT",
      "grid_max_hours": 6,
      "time_bracket_tolerance_seconds": 0.01,
      "observer_location_required": false,
      "eclipses_inferred": false
    }
  },
  "interpretation": {
    "locale": "en",
    "kind": "astrology/moon-phases",
    "disclaimer": "Symbolic reflection, not a verified prediction or professional advice.",
    "coverage": {
      "total_facts": 1,
      "selected_facts": 1,
      "omitted_count": 0,
      "selection_method": "all-source-facts-v1",
      "full_numeric_data_unchanged": true
    },
    "method": {
      "engine": "celestack-original-rules-v1",
      "corpus": "celestack-original-compositional-v1",
      "corpus_version": "2026-11-17.2",
      "fallback_locale": null,
      "editorial_status": "agent-authored; independent linguistic review pending",
      "predictive_validity": "symbolic interpretations are not scientifically validated predictions",
      "chinese_solar_terms": "numeric calendar output only; no rule paragraphs in this corpus"
    },
    "items": [
      {
        "fact_id": "astrology/moon-phases.events.1",
        "title": "First quarter",
        "text": "First quarter. Calculated time (UTC): 2026-11-17T11:47:49.647Z. Target elongation: 90°. This marks a lunar calendar phase, not a personal prediction. No eclipse is inferred.",
        "source": {
          "at": "2026-11-17T11:47:49.647Z",
          "phase": "first_quarter",
          "elongation_deg": 90.00000013,
          "target_elongation_deg": 90,
          "residual_deg": 1.293e-7,
          "id": "astrology/moon-phases.events.1",
          "type": "moon_phase"
        }
      }
    ]
  },
  "warnings": [],
  "credits_used": 10
}

The response preview selects whole fields and array entries for readability; no numeric values have been replaced. The full download preserves all fields, arrays and interpretation. The request_id is synthetic, and credits_used shows the configured successful-request cost; no credits were consumed.

cURL request — use your own API key and a new idempotency key
curl --request POST 'https://api.celestackapi.com/v1/astrology/moon-phases' \
+  --header 'Authorization: Bearer YOUR_API_KEY' \
+  --header 'Content-Type: application/json' \
+  --header 'Idempotency-Key: moon-phases-api-example-001' \
+  --data '{
  "locale": "en",
  "start_date": "2026-11-17",
  "days": 7
}'

Example computed 2026-11-17. Full fixture manifest, engine versions and SHA-256 checksums ↗

YOUR PRODUCT, YOUR EXPERIENCE

Ways to use it.

  • A lunar calendar or planning interface
  • Localized moon-phase notifications
  • A phase timeline shared across users

12 response locales

English, Ukrainian, Japanese, Spanish, French, German, Portuguese, Arabic, Italian, Hindi, Chinese and Korean.

Calculation values remain language-independent. Localized rule text is agent-authored; independent native-language review remains pending. Machine-readable field names stay stable.

KNOW THE CONVENTIONS

Limits and interpretation.

  • These are geocentric phase instants, not location-specific moonrise or moonset times.
  • The endpoint does not calculate eclipses or guarantee observation conditions.
  • A short date window can legitimately contain no principal phase event.

Interpretive content is for symbolic reflection and entertainment. It is not a verified personal prediction or professional advice. Read the API conventions ↗

PREDICTABLE ACCESS

Choose your billing.

Both options include 50,000 credits per monthly allowance, resetting monthly. No trial and no automatic overage. Custom needs use a contact form.

5,000credits per UTC day
60requests per minute
5,000new operation attempts per UTC day
32 MiBmaximum stored JSON result

Saved results: 7-day retention, up to 128 MiB per organization on this initial shared deployment, with a 512 MiB shared retained-result limit. Capacity can return a temporary error; there are no automatic extra charges. Production artifacts have separate retention. All usage and resource limits ↗. Checkout availability is shown in your account.

DEVELOPER QUESTIONS

Frequently asked questions.

Does the phase time depend on the user’s location?

The returned geocentric phase instant is the same worldwide. Convert the UTC timestamp into the user’s time zone for display.

Are eclipses included?

No. A new or full moon is not automatically an eclipse. Eclipse geometry and visibility are outside this endpoint.

Why can a result have no events?

Principal phases occur about a week apart. A short requested interval may contain no new moon, quarter or full moon; an empty events array is a valid result.

What does access cost?

Access is USD 39.99 per month or USD 199 billed annually, with no trial. Both billing options provide 50,000 credits per monthly allowance. 10 credits per started 30-day block; 1–365 days per request Daily credit, attempt, rate and resource limits apply. There are no automatic overage charges.

CONNECT THE BUILDING BLOCKS

Related APIs.

View every API